Review Assist
Transforma a sessão de um agente de codificação de IA em um Documento de Intenção revisável: o problema, as suposições, as alternativas rejeitadas e uma análise ancorada do diff.
Documentação
Review Assist
Revise código escrito por IA tão rápido quanto os agentes o escrevem.
Transforme a sessão de um agente de codificação em uma revisão de pull request guiada e verificável.
Instalar · Atualizar · Desinstalar · Como funciona · Arquitetura · Desenvolvimento · Contribuindo
Agentes de IA escrevem código mais rápido do que qualquer pessoa consegue ler diffs — e o contexto que torna a revisão rápida (o que foi pedido, o que foi assumido, o que foi tentado e abandonado, o que foi testado) é descartado no momento em que o PR é aberto. O Review Assist captura isso na fonte: a sessão de um agente se torna um Documento de Intenção, um validador prova que ele realmente cobre o diff, e um GitHub App o renderiza como uma revisão guiada sobre o pull request.
Totalmente open source, auto-hospedável e não armazena nenhum do seu código. Sua transcrição de sessão nunca sai da sua máquina. O aplicativo não tem banco de dados: ele lê o documento e o diff do GitHub por requisição com o token do próprio revisor, mantém-os em memória pela duração daquela requisição e os serve private, no-store a um visualizador que renderiza no navegador do revisor. Nada é gravado, mas seu código passa pelo serviço em trânsito — se isso importa para você, auto-hospede-o.
Instalar
Duas instalações únicas — o servidor MCP no lado do desenvolvedor, o GitHub App no lado do repositório.
1. Registre o servidor MCP com seu agente (para que ele possa criar Documentos de Intenção). Claude Code e Codex mantêm configurações separadas, então registrar em um não registra no outro — execute as seções que você usa.
Claude Code
claude mcp add -s user review-assist -- npx -y review-assist-mcp
A CLI e a extensão do VS Code compartilham esta única configuração -s user — mas apenas quando a extensão herda o PATH do seu shell (iniciada via code ., não pelo Dock). Iniciada pelo Dock, aplicativos GUI no macOS recebem apenas /usr/bin:/bin:/usr/sbin:/sbin, então npx não é encontrado e o servidor mostra não conectado sem erro. Registre sem npx:
npm install -g review-assist-mcp
claude mcp add -s user review-assist -- "$(which node)" "$(npm root -g)/review-assist-mcp/dist/index.js"
Codex
codex mcp add review-assist -- npx -y review-assist-mcp
Compartilhado com a extensão do IDE (~/.codex/config.toml) sob a mesma ressalva de code . acima. VS Code iniciado pelo Dock:
npm install -g review-assist-mcp
codex mcp add review-assist -- "$(which node)" "$(npm root -g)/review-assist-mcp/dist/index.js"
(Pule npm install -g se você já o executou para Claude Code — uma instalação global serve ambas as extensões; cada uma ainda precisa do seu próprio mcp add.)
Aplicativo de desktop do Claude — um clique, sem terminal:
baixe o .mcpb
e abra-o.
Um clique. Acesso somente leitura a código + comentários de PR, sem arquivos de workflow — ele adiciona a verificação automática em cada PR, o comentário de resumo e o visualizador de revisão guiada.
Atualizar
Relevante apenas se você usou o formulário de instalação global acima (npm install -g) — npx -y resolve para a versão mais recente em cada inicialização por conta própria.
npm install -g review-assist-mcp@latest
Reinicie seu agente depois para que ele recrie o processo do servidor.
Desinstalar
claude mcp remove -s user review-assist # or: codex mcp remove review-assist
npm uninstall -g review-assist-mcp # only if you used the global-install form
rm -rf ~/.review-assist # consent decisions and local run state
Como funciona
Ensinando as perguntas do seu repositório
O revisor faz um conjunto básico de perguntas que é o mesmo em todos os lugares. O que é verdadeiro apenas no seu repositório vai em uma pasta .reviewer/ na sua raiz: um invariante que um incidente passado custou, uma mudança que deve viajar com sua migração, um diretório cuja rotatividade nunca é incidental.
.reviewer/
README.md # the house rules
verification.md # what "verified" means here, per area
Markdown, commitado com o código, revisado como qualquer outra coisa. O revisor lê a pasta após o diff e antes da sua primeira pergunta, então o que você escreve lá chega na primeira rodada. Ele adiciona perguntas e afia as que o diff provocou; ele não pode adicionar um campo de schema, relaxar uma verificação ou dispensar a entrevista. A maioria dos repositórios não precisa de nenhuma, e uma pasta ausente não muda nada. Este repositório tem a sua própria.
Arquitetura
Três sistemas e dois atores externos. Sua máquina produz a mudança e seu Documento de Intenção; a transcrição da sessão nunca a deixa. O GitHub mantém o pull request e cada peça durável do estado da revisão. O aplicativo reage a eventos pull_request e publica a verificação como sua identidade de bot, depois serve a revisão guiada, lendo e escrevendo no GitHub como o revisor conectado.
A destilação de dois agentes — autor e revisor como contextos separados com papéis bloqueados, e as ferramentas que cada um pode alcançar — é uma visão em nível de componente, mantida em docs/ARCHITECTURE.md junto com a lista completa de rotas.
Desenvolvimento
| Caminho | Componente |
|---|---|
packages/schema | O formato — JSON Schema (draft 2020-12) + tipos TypeScript |
packages/validator | CLI + biblioteca review-assist: as cinco verificações e o renderizador Markdown |
packages/mcp-server | Servidor MCP que conduz a destilação e controla o acesso às submissões |
apps/github-app/worker | Cloudflare Worker sem estado: intermediário OAuth + proxy fino do GitHub |
apps/github-app/viewer | Visualizador de revisão guiada no lado do cliente |
SPEC.md | O design congelado: as seis seções do documento e as cinco verificações |
npm install
npm run build
# Validate and render the example Intent Document
node packages/validator/dist/cli.js validate packages/schema/src/example.json
node packages/validator/dist/cli.js render packages/schema/src/example.json
# Preview the guided viewer with mock data → http://localhost:8787/#acme/checkout-service/pull/42
node scripts/mockserver.mjs
# Tests
npx vitest run
Arquitetura e detalhes internos: docs/ARCHITECTURE.md.
Contribuindo
Issues e pull requests são bem-vindos. Se a revisão guiada parecer errada em um dos seus pull requests, abra uma issue com o Documento de Intenção e o diff que a produziu — esse par geralmente é suficiente para reproduzir. Propostas para mudar o próprio formato valem a pena ser levantadas como issue primeiro, já que SPEC.md está deliberadamente congelado e qualquer mudança se espalha pelo validador, pelo visualizador e por cada documento já commitado.
Antes de abrir um pull request, execute as verificações em Desenvolvimento; o CI executa o mesmo build, typecheck, testes e validação de exemplos.