Guia Completo do Oh My Paper: do levantamento bibliográfico à publicação do artigo, resolva tudo em um único terminal

Comece em 20 minutos | 5 Agentes em colaboração + 34 habilidades de pesquisa | Transforme o Claude Code no seu laboratório de pesquisa dedicado

---

Visão geral do projeto

Oh My Paper é um plugin open source para o Claude Code. O problema que ele resolve é bem direto: o Claude Code pode te ajudar a escrever código, mas o trabalho de pesquisa vai muito além de programar — você também precisa fazer levantamento bibliográfico, avaliar oportunidades de inovação, planejar experimentos, escrever o artigo e conferir citações, e nenhuma dessas etapas tem uma ferramenta realmente boa para conectá-las em um fluxo contínuo.

A abordagem do Oh My Paper é “instalar” no Claude Code uma esteira de pesquisa estruturada: 5 agentes com funções especializadas cuidam de partes específicas, 34 habilidades de pesquisa são carregadas conforme a necessidade e, em segundo plano, hooks automáticos mantêm o estado do projeto sempre registrado. Depois de configurar tudo, sempre que você abrir o Claude Code ele pergunta “O que você vai fazer hoje?”, ou seja, qual papel você deseja assumir; em seguida, ele carrega automaticamente o arquivo de memória correspondente e retoma do ponto em que você parou. Não é necessário nenhum GUI: todas as ações acontecem no terminal.

---

Perfil do público-alvo

Este artigo é para desenvolvedores que:

• têm de 1 a 5 anos de experiência em desenvolvimento e já passaram (ou estão passando) pelo processo de escrever artigos e fazer pesquisa
• querem usar IA para auxiliar a pesquisa, mas não gostam de ficar alternando entre várias ferramentas
• têm interesse nos conceitos de colaboração em modo Agentes e isolamento de memórias entre papéis, e querem exemplos práticos

Se você já tem um direcionamento claro para pesquisa (por exemplo, CV, NLP, arquitetura de sistemas) ou está realizando pesquisas técnicas internas na empresa, a esteira do Oh My Paper se aplica ao seu caso.

---

Dependências principais e ambiente

Antes de começar, verifique se seu ambiente atende aos requisitos abaixo:

---

Árvore completa de estrutura do projeto

Depois de executar /omp:setup, a estrutura do diretório do projeto fica assim:

my-research/
├── paper/                     # Área de trabalho do artigo em LaTeX
│   ├── main.tex
│   ├── sections/            # Arquivos .tex de cada seção
│   └── refs/                 # Arquivos .bib de referências
├── experiment/                # Código e scripts dos experimentos
├── survey/                    # Saídas do levantamento bibliográfico
├── ideation/                  # Pontos de inovação e resultados de avaliação
├── promotion/                 # Slides, demos e materiais de divulgação
├── skills/                    # Habilidades customizadas locais do projeto
├── .pipeline/
│   ├── tasks/
│   │   └── tasks.json        # Árvore de tarefas para todas as etapas
│   ├── docs/
│   │   └── research_brief.json
│   └── memory/               # Arquivos de memória dos Agentes
│       ├── project_truth.md   # Linha de base do projeto + log de progresso
│       ├── orchestrator_state.md
│       ├── execution_context.md
│       ├── experiment_ledger.md
│       ├── result_summary.md
│       ├── review_log.md
│       ├── literature_bank.md
│       ├── agent_handoff.md
│       └── decision_log.md
├── .claude/
│   └── settings.json         # Registro do hook SessionStart
├── CLAUDE.md
└── AGENTS.md

---

Passo a passo de instalação

Etapa 1: Adicionar o mercado de plugins

No Claude Code, execute o comando abaixo para registrar o endereço do mercado de plugins do Oh My Paper:

/plugin marketplace add LigphiDonk/Oh-my--paper

Essa etapa não exige que você clone o repositório inteiro: o Claude Code vai buscar a lista de plugins no mercado.

Etapa 2: Instalar o plugin

/plugin install omp@oh-my-paper

Após a instalação, execute /plugin para verificar:

/plugin
# A saída esperada deve incluir: omp @ oh-my-paper, Status: Enabled

Etapa 3: Reiniciar o Claude Code

Feche totalmente a janela atual do Claude Code e abra novamente.

Etapa 4: Inicializar o projeto de pesquisa

Entre no diretório do seu projeto de pesquisa e execute:

/omp:setup

Esse comando faz três coisas:

1. Cria o diretório .pipeline/ e todos os seus subdiretórios e arquivos de memória
2. Registra o hook SessionStart em .claude/settings.json
3. Gera um tasks.json e um research_brief.json padrão

Após a inicialização, a estrutura do diretório fica igual à “Árvore completa de estrutura do projeto” mostrada acima.

Verificar se a instalação funcionou

Abra novamente o Claude Code (dentro do diretório do projeto que você inicializou). Você deve ver o Claude exibindo o menu de seleção de papéis, perguntando qual papel você quer assumir para começar a trabalhar hoje. Se aparecer, significa que a instalação completa deu certo.

---

Detalhamento da esteira de pesquisa em 5 etapas

O Oh My Paper divide o fluxo de pesquisa inteiro em 5 etapas; cada etapa corresponde a um comando e a um conjunto de habilidades recomendadas.

Etapa 1｜Survey: Levantamento bibliográfico

Execute o comando:

/omp:survey

O que esta etapa faz: faz com que o Claude pesquise artigos relacionados com base no seu tema de pesquisa, extraia resumos e informações-chave e, ao final, organize tudo em um arquivo literature_bank.md.

Habilidades comuns:

• paper-finder — busca trabalhos relacionados no ArXiv e no Semantic Scholar
• paper-analyzer — extrai contribuições centrais, métodos e limitações
• biorxiv-database — se você estiver em biomedicina, busca no BioRxiv

Arquivo principal de saída: survey/literature_bank.md

Fluxo de trabalho típico:

Você: /omp:survey
→ O Claude pergunta palavras-chave do seu tema de pesquisa
→ Busca automática → organiza fichas bibliográficas → grava em literature_bank.md
→ Exibe o resumo do levantamento bibliográfico para você confirmar se precisa complementar

Etapa 2｜Ideation: Geração de ideias de inovação

Execute o comando:

/omp:ideate

Com base no resultado do levantamento bibliográfico da etapa 1, o Claude gera possíveis ideias de inovação e avalia a viabilidade de cada uma.

Habilidades comuns:

• inno-idea-generation — brainstorming em larga escala de ideias
• inno-idea-eval — pontua em três dimensões: novelty, feasibility e impact
• research-idea-convergence — converge para 2-3 direções com maior potencial

Arquivo principal de saída: resultados de avaliação no diretório ideation/

Etapa 3｜Experiment: Desenho e execução do experimento

Execute o comando:

/omp:experiment

Esta etapa cobre o escopo mais amplo: desenho do plano experimental, escrita do código de avaliação, execução local ou remota e análise dos resultados.

Habilidades comuns:

• inno-experiment-dev — gera a estrutura do código dos experimentos
• research-experiment-driver — gerencia o ciclo de iteração dos experimentos
• remote-experiment — acessa um nó remoto de GPU via SSH e executa o experimento (veja a seção “Experimentos remotos”)

Arquivo principal de saída: diretório experiment/ + experiment_ledger.md (histórico dos experimentos)

Etapa 4｜Publication: Escrita das seções do artigo

Execute o comando:

/omp:write

Converte os resultados do experimento em texto do artigo, gera gráficos e títulos e gerencia os arquivos LaTeX.

Habilidades comuns:

• inno-paper-writing — geração geral de seções
• ml-paper-writing — template de artigo para Machine Learning/IA
• scientific-writing — normas de escrita acadêmica (tempos verbais, escolhas de palavras, estrutura)
• inno-figure-gen — gera código de gráficos (Matplotlib, Plotly)
• inno-reference-audit — verifica automaticamente se o formato das citações está correto

Arquivo principal de saída: arquivos LaTeX no diretório paper/

Etapa 5｜Promotion: Divulgação dos resultados

Execute o comando:

/omp:plan
# Na etapa Promotion, escolha habilidades relacionadas à criação de materiais de apresentação

Converte resultados do artigo em slides de apresentação, blogs técnicos, propostas de Grant etc.

Habilidades comuns:

• making-academic-presentations — geração de PPT para relatórios acadêmicos
• inno-grant-proposal — escrita de pedido de financiamento
• inno-rclone-to-overleaf — sincroniza automaticamente o LaTeX local para o Overleaf

---

As 5 funções de Agente e o mecanismo de isolamento de memórias

Este é o conceito de design mais central do Oh My Paper.

Visão geral das funções de Agente

Princípio do isolamento de memórias

Cada agente só pode ler/escrever arquivos de memória dentro do escopo das suas próprias responsabilidades; ele não consegue ver o estado interno dos outros agentes. A principal vantagem desse desenho é evitar poluição de contexto — por exemplo, o Paper Writer não vai ver os resultados intermediários de depuração do Experiment Driver, e o Literature Scout não vai se deixar influenciar na avaliação bibliográfica por ter visto dados experimentais.

A comunicação entre funções acontece por meio de dois “espaços públicos”:

tasks.json         ← Todos os agentes leem/escrevem, registrando o status de conclusão das tarefas
project_truth.md   ← Todos os agentes adicionam entradas, registrando o progresso geral do projeto

Sincronização automática de estado

O detalhe de design mais importante: o Conductor atualiza automaticamente esses dois arquivos públicos após cada subtarefa ser concluída; você não precisa lembrar de fazer isso manualmente.

Subtarefa concluída
  → Conductor marca automaticamente a tarefa correspondente em tasks.json como done
  → Conductor adiciona automaticamente um registro de progresso em project_truth.md
    → Na próxima sessão aberta, o Claude lê esses dois arquivos e retoma do ponto onde parou

---

Consulta rápida das 34 habilidades de pesquisa

O Oh My Paper vem com 34 habilidades de pesquisa integradas, cobrindo todo o fluxo de pesquisa. Abaixo elas estão organizadas por categoria para facilitar a busca sob demanda:

Bibliografia (Literatura)

• paper-finder — busca de artigos em bases de dados cruzadas
• paper-analyzer — extração de contribuições centrais do artigo
• paper-image-extractor — extração de gráficos a partir de PDFs
• research-literature-trace — rastreia cadeias de citações de um artigo
• biorxiv-database — busca especializada no BioRxiv
• dataset-discovery — descoberta de datasets relacionados

Levantamento e criatividade

• inno-deep-research — modo de pesquisa aprofundada
• gemini-deep-research — integração do Gemini para pesquisa aprofundada
• inno-code-survey — levantamento de implementação em código
• inno-idea-generation — geração em lote de ideias de inovação
• inno-idea-eval — avaliação multidimensional de ideias
• research-idea-convergence — convergência para a melhor direção

Experimentos

• inno-experiment-dev — geração de código dos experimentos
• inno-experiment-analysis — análise dos resultados dos experimentos
• research-experiment-driver — gerenciamento iterativo dos experimentos
• remote-experiment — ciclo remoto de experimentos em GPU

Escrita

• inno-paper-writing — seções do artigo em geral
• ml-paper-writing — artigo para ML/IA
• scientific-writing — normas de escrita acadêmica
• inno-figure-gen — geração de gráficos
• inno-reference-audit — auditoria do formato das citações
• research-paper-handoff — normas de handoff entre agentes

Planejamento e revisão

• inno-pipeline-planner — planejamento da esteira
• research-pipeline-planner — planejamento das etapas de pesquisa
• inno-paper-reviewer — avaliação de qualidade do artigo
• inno-prepare-resources — lista de preparação de recursos
• inno-rclone-to-overleaf — sincronização com o Overleaf

Demonstrações e propostas

• making-academic-presentations — apresentações (PPT) para relatórios acadêmicos
• inno-grant-proposal — proposta de solicitação de financiamento

Agendamento de Agentes

• claude-code-dispatch — delega subtarefas ao Claude Code
• codex-dispatch — delega tarefas em paralelo ao Codex

Foco por área

• academic-researcher — pesquisa acadêmica geral
• bioinformatics-init-analysis — análise inicial em bioinformática
• research-news — acompanhar as novidades no campo de pesquisa

As habilidades são carregadas sob demanda. Ao executar /omp:survey, o Claude recomendará habilidades relacionadas automaticamente; você também pode adicionar habilidades personalizadas no diretório skills/.

---

Demonstração completa do fluxo de trabalho típico

Vamos usar como exemplo um artigo na área de IA e passar por completo a esteira de 5 etapas.

Etapa 1: Inicialização do projeto

# Entre no diretório de pesquisa
cd ~/research/my-paper

# No Claude Code:
/omp:setup
# Saída: .pipeline/ criada, hook SessionStart registrada

Etapa 2: Levantamento bibliográfico

# No Claude Code:
/omp:survey
# → Claude pergunta: “Qual é o seu tema de pesquisa?”
# → Entrada: LLM reasoning, chain-of-thought prompting
# → Claude busca automaticamente no ArXiv/Semantic Scholar
# → Organiza 20+ trabalhos relacionados em survey/literature_bank.md
# → Gera o resumo do levantamento para você confirmar se é preciso completar

Etapa 3: Geração de ideias de inovação

/omp:ideate
# → Claude lê literature_bank.md
# → Gera 8 ideias potenciais de inovação
# → Para cada ideia, pontua em novelty / feasibility / impact
# → Converge para 2 direções e grava em research_brief.json

Etapa 4: Desenho e execução do experimento

/omp:experiment
# → Claude lê research_brief.json
# → Desenha o plano experimental (baseline, métodos de comparação, métricas de avaliação)
# → Gera o código dos experimentos no diretório experiment/ 
# → Executa avaliação local e interpreta os resultados das métricas
# → Grava os resultados em experiment_ledger.md

Se precisar executar em um nó remoto de GPU:

# Configure o nó de computação remota (crie compute-config.json em experiment/)
{
  "host": "gpu-server.example.com",
  "user": "researcher",
  "key_path": "~/.ssh/id_rsa",
  "remote_dir": "/home/researcher/experiments"
}

# No Claude Code:
/omp:experiment
# → Claude detecta compute-config.json
# → Usa a habilidade remote-experiment
# → rsync envia código para o remoto → executa via SSH → puxa os resultados
# → Analisa metrics automaticamente e grava em experiment_ledger.md

Etapa 5: Escrita das seções do artigo

/omp:write
# → Claude lê experiment_ledger.md + literature_bank.md
# → Gera Introduction / Method / Experiment (arquivos .tex)
# → Gera gráficos (scripts Matplotlib) e compila para paper/figures/
# → Revisão de citações: verifica o formato do arquivo .bib

Etapa 6: Revisão por pares

/omp:review
# → Claude lê como Reviewer
# → Verifica consistência lógica, clareza na descrição do método e suficiência das comparações experimentais
# → Gera review_log.md com sugestões de mudanças
# → Após aplicar as sugestões, rode /omp:review novamente até passar

Etapa 7: Sincronizar para o Overleaf

# No diretório skills/, configure a sincronização com o Overleaf
# Use a habilidade inno-rclone-to-overleaf
# O Claude sincroniza automaticamente o diretório local paper/ para o projeto no Overleaf

---

Detalhamento de experimentos remotos

Para experimentos que exigem poder computacional de GPU, o Oh My Paper suporta um ciclo completo de experimentos remotos.

Fluxo de arquitetura

Desenho local do plano
  → gera o código do experimento
    → rsync para o servidor remoto
      → login via SSH no nó remoto
        → executa o experimento na GPU
          → baixa os logs de metrics
            → interpreta as métricas localmente
              → verifica se atingiu o limiar
                → otimiza iterativamente / encerra o experimento

Configurar o nó remoto

Crie compute-config.json no diretório experiment/:

{
  "host": "your-gpu-server.com",
  "user": "researcher",
  "ssh_key": "~/.ssh/id_rsa",
  "remote_workspace": "/home/researcher/omp-experiments",
  "max_iterations": 5,
  "success_threshold": {
    "accuracy": 0.92,
    "latency_ms": 200
  }
}

Rodar o experimento remoto

# No Claude Code:
/omp:experiment
# → detecta compute-config.json
# → executa automaticamente: sincroniza código → roda via SSH → puxa os resultados
# → se as métricas não atingirem o alvo, ajusta automaticamente os hiperparâmetros e reexecuta (até max_iterations vezes)
# → grava o resultado final em experiment_ledger.md

---

Delegação de tarefas ao Codex

Se algum experimento envolver uma grande quantidade de geração repetitiva de código (por exemplo, rodar 10 conjuntos de diferentes configurações de hiperparâmetros), você pode pedir ao Conductor que delegue as tarefas para o Codex e processe em paralelo.

/omp:delegate
# → Conductor lê o contexto atual da tarefa
# → gera um prompt completo para o Codex
# → você copia para um novo terminal: codex "..."
# → Codex executa em um terminal independente
# → ao terminar, escreve no agent_handoff.md um sinal CODEX_DONE
# → o Conductor detecta o sinal, lê os resultados e atualiza tasks.json

A vantagem desse desenho: o Claude Code e o Codex rodam ao mesmo tempo em terminais diferentes. Assim, seu Claude Code local não fica ocupado e você pode fazer outras tarefas, como organização bibliográfica, em paralelo.

---

Solução de problemas comuns

Q1: Após executar /omp:setup, ao abrir o Claude Code não aparece o menu de seleção de papéis

Causa: o hook SessionStart não foi registrado corretamente.

Passo a passo de verificação:

1. Verifique se existe .claude/settings.json no diretório do projeto
2. Verifique se esse arquivo contém a seção de configuração hooks

cat .claude/settings.json
# confirme que há "hooks": { "SessionStart": [...] } 

Se não houver, execute /omp:setup novamente para re-inicializar e garanta que o Claude Code tenha sido reiniciado completamente.

---

Q2: A instalação do plugin funcionou, mas comandos como /omp:survey mostram “comando não reconhecido”

Causa: o plugin não foi carregado corretamente, ou o Claude Code precisa ser reiniciado.

Passos de solução:

# 1. Desinstale e reinstale
/plugin uninstall omp
/plugin install omp@oh-my-paper

# 2. Reinicie completamente o Claude Code (feche todas as janelas)

# 3. Verifique o status do plugin
/plugin

---

Q3: O Literature Scout encontrou artigos demais ou poucos demais; quero ampliar o escopo da busca

Causa: as palavras-chave iniciais estão boas demais (muito específicas) e restringem os resultados.

Como resolver:

Ao rodar /omp:survey, forneça várias formas equivalentes e termos mais amplos:
Entrada: "LLM reasoning, chain-of-thought, CoT, deliberate reasoning, LLM planning"
Em vez de apenas: "LLM reasoning"

Além disso, no arquivo skills/paper-finder.md, você pode adicionar fontes adicionais de banco de dados (por exemplo, ACL Anthology, página oficial do ICLR).

---

Q4: As descrições dos experimentos geradas pelo Paper Writer não batem com os resultados reais

Causa: o Experiment Driver e o Paper Writer não sincronizaram o experiment_ledger.md mais recente a tempo.

Como resolver:

Após concluir cada iteração do experimento, antes de o Paper Writer começar, rode /omp:plan para o Conductor sincronizar o estado global e garantir que o Paper Writer leia os resultados mais recentes:

/omp:plan
# → Conductor mostra o status atual do tasks.json
# → confirme que a tarefa de experiment foi marcada como done
# → então rode /omp:write

---

Q5: A sincronização rsync de experimento remoto falhou e aparece “permission denied”

Causa: permissões incorretas da chave SSH, ou o diretório remoto não existe.

Passos de verificação:

# 1. Verifique as permissões da chave SSH local
chmod 600 ~/.ssh/id_rsa

# 2. Teste a conexão SSH (login sem senha)
ssh -i ~/.ssh/id_rsa [email protected] "echo ok"

# 3. Garanta que o diretório remoto existe
ssh [email protected] "mkdir -p /home/researcher/omp-experiments"

# 4. Verifique se o remote_workspace no compute-config.json está correto

---

Q6: Depois da delegação ao Codex, o Conductor fica esperando o sinal CODEX_DONE o tempo todo

Causa: quando o Codex terminou, ele não gravou corretamente agent_handoff.md.

Como resolver:

1. Verifique se o terminal onde o Codex rodou finalizou corretamente
2. Adicione manualmente uma linha no final do .pipeline/memory/agent_handoff.md:

CODEX_DONE
result: [preencha com o resultado de saída do Codex]

1. Em seguida, continue o fluxo de trabalho atual no Claude Code

---

Leitura adicional e caminhos de evolução

1. Expansão de habilidades personalizadas

O Oh My Paper permite adicionar habilidades personalizadas no diretório local skills/ do projeto. Crie o formato assim:

---
name: my-custom-skill
description: fluxo de análise personalizado para um domínio específico de pesquisa
stage: survey  # opcional: survey | ideation | experiment | write | review
---

# Título da habilidade

## Passos de execução
1. Ler arquivos de contexto ...
2. Executar tarefa específica ...

Depois de registrar, ao rodar comandos como /omp:survey, o Claude vai recomendar automaticamente as habilidades customizadas relacionadas.

2. Evoluir a colaboração com múltiplos Agentes

Se você estiver tocando vários temas de pesquisa ao mesmo tempo, pode rodar /omp:setup em diferentes subdiretórios. Assim, cada subprojeto terá um .pipeline/ e uma equipe de Agentes independentes. A função do Conductor cuida da visão geral e da coordenação entre os subprojetos.

3. Fluxo de trabalho colaborativo com Overleaf

Com a habilidade inno-rclone-to-overleaf, ao sincronizar o artigo local para o Overleaf, você pode convidar seu orientador para comentar diretamente no Overleaf; após concluir as revisões, sincronize de volta para o local. Todo o processo dispensa upload/download manual.

4. Integrar com outros backends de LLM

O Oh My Paper depende do Claude Code em si, mas na etapa de experimentos você pode configurar diferentes LLMs para comparação e avaliação. No diretório experiment/, crie um arquivo de configuração do modelo:

# experiment/model_configs.py
llm_configs = {
    "claude-sonnet": {"provider": "anthropic", "model": "claude-3-5-sonnet"},
    "gpt-4o": {"provider": "openai", "model": "gpt-4o"},
    "gemini-pro": {"provider": "google", "model": "gemini-1.5-pro"},
}

Depois, no código do experimento, referencie essas configurações para comparação lado a lado.

5. Acompanhar as novidades mais recentes da pesquisa

Use a habilidade research-news para fazer varreduras regulares dos commits mais recentes do ArXiv, filtrar os novos trabalhos relacionados ao seu tema e atualizar automaticamente literature_bank.md. Você também pode combinar com tarefas agendadas do cron para atualizar a base bibliográfica automaticamente uma vez por semana.