conclave-ai
v0.25.0
Published
Graph-aware independent validator for code changes and agent claims
Downloads
1,095
Maintainers
Readme
Conclave
Um companheiro de PR que transforma mudanças de código em evidências revisáveis.
Conclave simplifica e protege o caminho entre o código alterado e o merge aprovado por uma pessoa.
Início rápido · CLI · Cockpit · Skill de agente · GitHub Actions · FAQ
O Conclave fica entre uma mudança de código e a aprovação dela. Ele compara a mudança real do Git, mapeia o código ao redor e aponta riscos com evidência de arquivo e linha, depois entrega a próxima ação para você, para o seu coding agent ou para quem vai revisar.
mudança → review do Conclave → agente corrige → Conclave confere de novo → humano aprova → mergeConteúdo
- Por que o Conclave
- Instalação
- Início rápido
- Um motor, três jeitos de usar
- Inteligência de Repositório
- Receitas
- Vereditos e códigos de saída
- Configuração
- Privacidade e segurança
- Comparação com outras ferramentas
- Perguntas frequentes
- Solução de problemas
- Documentação
Por que o Conclave
- Revisa a mudança que você tem de verdade. Commits da branch e arquivos preparados, alterados e novos numa única passada, contra uma base detectada automaticamente.
- Segue o raio de impacto. Um grafo local de código encontra quem chama, importa e consome o que você mudou, inclusive fora do diff.
- Evidência, não achismo. Todo achado aponta arquivo e linha e diz o que fazer. Nenhum achado afirma mais do que a regra verificou.
- Feito para coding agents. Cada review gera um prompt de correção, e a nova conferência distingue progresso real do mesmo diff reenviado, de estagnação e de regressão.
- Privado e gratuito por padrão. O review roda localmente e de forma determinística: sem chave de API, sem código enviado a modelo, sem telemetria.
- Somente leitura. O Conclave nunca altera arquivos, faz commit, push, aprovação ou merge.
- Qualquer repositório. Grafo de código e regras de defeito para TypeScript, JavaScript, Python e Java; qualquer outro arquivo de texto ainda conta para escopo e diff.
Instalação
Requisitos: Node.js 20+ e Git. O projeto revisado pode ser de qualquer linguagem.
npm install -g conclave-ai # recomendado: uma instalação para todos os repositóriosOutras opções:
npm install --save-dev conclave-ai # por projeto, depois: npx conclave check .
yarn add --dev conclave-ai # depois: yarn conclave check .
pnpm add --save-dev conclave-ai # depois: pnpm exec conclave check .
npx --yes conclave-ai@latest check . # rodar uma vez sem instalarConfira a instalação com conclave --version e conclave doctor ..
Início rápido
cd seu-repositorio
conclave check .Exemplo de saída para uma branch que adicionou um parâmetro de senha ao login():
Current workspace vs master · 1 file changed · 2 affected
WARN 3 risks
⚠ src/auth.ts:2 Changed code has an empty catch block
→ Handle, rethrow or record the error, or document why ignoring this failure is correct.
⚠ src/app.ts:1 The change affects code outside the diff
→ Review the affected callers, references, imports, and contracts before accepting the resolution.
⚠ src/auth.ts:1 Exported behavior changed without a test change
→ Add or identify existing coverage that proves the changed public behavior.
Next: Review the findings, correct confirmed problems and collect the missing verification evidence.
5 items still need verification
Agent prompt: conclave handoff . · Details: --verbose · Browser: conclave open .--verbose mostra o relatório completo: cada achado com sua evidência, o que ainda falta verificar e os desafios independentes que valem a pena rodar. Todo review também fica salvo no histórico local. Com conclave config --language pt-BR, a saída aparece em português.
Não sabe o que rodar? Digite conclave para abrir o menu guiado, ou conclave help <comando> para qualquer comando.
Um motor, três jeitos de usar
| | Produto | Ideal para | Comece com | Guia |
| --- | --- | --- | --- | --- |
| ⌨️ | CLI | Terminal, scripts e CI | conclave check . | Guia da CLI |
| 🖥️ | Cockpit | Ler resultados, diffs e histórico no navegador | conclave open . | Guia do cockpit |
| 🤖 | Skill de agente | Fazer o Claude Code ou o Codex revisar o próprio trabalho antes do merge | conclave setup . | Guia da skill |
Como biblioteca:
import { check, ask } from "conclave-ai";
const { verdict, handoff } = await check({ repository: ".", objective: "Proteger o fluxo de login" });
const answer = await ask("Onde a sessão é renovada?");Sem objective, ele é inferido do último commit (objectiveInferred informa). Os comandos do dia a dia são check, ask, investigate, open, history, handoff, init, config e doctor; o resto fica em conclave tools.
E ainda um workflow pronto de GitHub Actions que comenta em cada pull request. Todos usam o mesmo motor local e compartilham configurações e histórico.
Inteligência de Repositório
O review olha para uma mudança. A Inteligência de Repositório olha para o repositório inteiro como está no disco e guarda o que encontra, para que uma pessoa decida o que fazer.
conclave audit . # Static: regras determinísticas, sem modelo, sem rede
conclave audit . --semantic # Smart: um modelo também lê regiões limitadas e propõe hipóteses
conclave audit . --semantic --deep # Deep: os papéis de raciocínio questionam cada hipótese
conclave findings list # o que as auditorias registraram
conclave open . # o mesmo, no cockpit| Modo | O que roda | Sai da sua máquina | | --- | --- | --- | | Static | Seis regras determinísticas sobre o código indexado e o grafo de imports | Nada | | Smart | Static, depois um modelo lê regiões limitadas e um verificador checa cada hipótese | Código sanitizado dessas regiões, para o provider que você configurou | | Deep | Static, depois descoberta e os cinco papéis de raciocínio em cada hipótese | O mesmo que Smart, com várias vezes mais chamadas |
Smart e Deep vêm desligados, param no orçamento que você definir e mostram provider, modelos e orçamento antes da primeira chamada. No cockpit, só iniciam depois que você confirma esse aviso.
Uma hipótese não é um defeito verificado. O Conclave mantém as duas coisas separadas em todo lugar:
| | Achado estático | Hipótese da IA |
| --- | --- | --- |
| Vem de | Uma regra que bateu com o código | A leitura que um modelo fez do código |
| Pode reprovar --fail-on | Sim | Nunca |
| "Model-supported" significa | Não se aplica | Uma segunda leitura de modelo concordou. Não é confirmação nem reprodução |
| Vira confirmado quando | Uma pessoa classifica | Uma pessoa classifica |
Nada é executado, então nada é relatado como reproduzido. Uma auditoria sem achados não é evidência de que o código está correto.
Findings inbox e propostas de issue. Cada auditoria é registrada em um registro local (.conclave/findings/ledger.json) que acompanha cada achado como novo, persistente, resolvido ou reaparecido. Você classifica os achados (confirmed, false-positive, accepted-risk, needs-investigation), cria uma proposta de issue a partir de um deles, edita e aprova uma revisão exata. Editar o texto, reclassificar o achado ou mudar o código por trás dele invalida a aprovação.
A publicação no GitHub não está implementada. As propostas ficam locais: nenhum comando, ação do cockpit ou rota de API cria uma issue no GitHub, e conclave issues publish retorna um erro.
No cockpit. conclave open . agora abre em Overview e traz Repository audits, Findings inbox, Issue proposals e Architecture ao lado de Review, Ask e Investigate. Guia do cockpit → · Auditoria de repositório → · Fluxo de achados → · Descoberta semântica →
Receitas
Revisar antes de abrir o pull request
conclave check . --objective "Adicionar login sem senha sem quebrar a restauração da sessão"Comparar duas branches sem trocar o checkout
conclave compare . # escolher numa lista
conclave compare . --base origin/main --head feature/login --objective "Adicionar login sem senha"Passar os achados ao coding agent e conferir de novo
conclave check . --json > review.json
conclave handoff . # prompt para colar no agente
# …o agente corrige…
conclave check . --previous-report review.json # mesma série: progresso, estagnação ou regressãoDeixar o agente fazer isso por você
conclave setup .
# depois peça ao Claude Code ou Codex: "Está pronto para merge? Confere com o Conclave."Bloquear o CI pelo veredito
conclave setup . --agents none --github-actions # ou, em qualquer CI:
conclave check . --base origin/main --json > conclave.json # saída 1 = BLOCK, 2 = INCONCLUSIVEUsar o relatório em scripts
conclave check . --json | jq '.report.findings[] | {severity, title, file: .evidence[0].path, line: .evidence[0].startLine}'O JSON tem três campos de topo: summary, report (veja o schema) e handoff. Os nomes dos campos são estáveis e sempre em inglês.
Vereditos e códigos de saída
| Veredito | Saída | Significado | Próxima ação |
| --- | ---: | --- | --- |
| PASS | 0 | Nenhum blocker ou warning determinístico encontrado | Rodar seus testes e pedir review humano |
| WARN | 0 | Ainda existe um risco a revisar | Inspecionar ou corrigir e conferir de novo |
| BLOCK | 1 | A evidência contradiz escopo, claims ou segurança estrutural | Enviar o handoff ao coding agent e conferir de novo |
| INCONCLUSIVE | 2 | A evidência não permite uma conclusão segura | Melhorar base, objetivo ou critérios |
PASS é evidência, não aprovação. Uma comparação sem arquivos alterados mostra "Nothing to review". Como o review funciona →
Configuração
O review e a auditoria Static não precisam de configuração nem de chave. Um modelo só é usado pelos modos opcionais Ask e Investigate e por uma auditoria Smart ou Deep:
conclave init # provider → modelo → chave de API, três passos
conclave config # mostra cada configuração e de onde ela vem
conclave config set api-key # troca a chave (entrada oculta)
conclave config set model deepseek-v4.1-flash
conclave config --language pt-BR # interface em português ou espanhol (es-ES)| Provider | Observações | | --- | --- | | OpenCode Go | Padrão recomendado de baixo custo | | OpenAI, Anthropic, OpenRouter | Perfis de modelo mantidos; qualquer ID de modelo funciona | | Ollama, LM Studio | Totalmente local, nada sai da sua máquina; veja modelos locais |
As configurações ficam por usuário em ~/.config/conclave/credentials.env (permissão só do dono). Variáveis do shell têm prioridade, depois um .env do projeto, depois as configurações do usuário. Todas as configurações e variáveis de ambiente →
Privacidade e segurança
| | Review (check, compare, review) | Ask / Investigate |
| --- | --- | --- |
| Código enviado a modelo | Nunca | Trechos limitados, só ao provider que você configurou |
| Chamadas de rede | Nenhuma | Só o seu provider |
| Precisa de chave de API | Não | Sim (ou um modelo local) |
| Executa scripts do repositório | Nunca | Nunca |
| Telemetria | Nenhuma | Nenhuma |
O Conclave só grava em .conclave/ no seu repositório (cache do mapa de código, histórico, critérios) e na sua pasta de configurações de usuário. conclave audit se comporta como o review (sem modelo, sem rede), a menos que você use --semantic, que envia regiões limitadas e sanitizadas ao seu provider, como o Ask. O cockpit escuta apenas em 127.0.0.1, e o navegador nunca recebe a sua chave de API. Veja limites de segurança.
Comparação com outras ferramentas
| | Encontra | Precisa de | Papel do Conclave |
| --- | --- | --- | --- |
| Type checker / linter | Erros de tipo, estilo, padrões ruins conhecidos | Setup de build | Complementar. Anexe os resultados a um review com --receipt. |
| Suíte de testes | Regressões de comportamento cobertas | Testes | Complementar. O Conclave aponta código público alterado sem teste alterado. |
| Revisor de código com IA | Qualquer coisa, com precisão variável | Enviar código a um modelo | O Conclave é determinístico e local; raciocínio de modelo é opcional e separado do veredito. |
| Conclave | Desvio de escopo, raio de impacto, testes faltando, erros engolidos, claims não cumpridas | Git | Evidência e próxima ação para quem decide, pessoa ou agente. |
Perguntas frequentes
O Conclave envia meu código para algum lugar? Não durante o review nem em uma auditoria Static. Só Ask, Investigate e uma auditoria Smart ou Deep chamam um modelo, e apenas o provider que você configurou. Com Ollama ou LM Studio, nada sai da sua máquina.
É gratuito? Sim, licença MIT, e o review não custa nada para rodar. Ask e Investigate custam o que o seu provider cobra; o preset Essential mediu cerca de US$ 0,0015 por execução no nosso product lab.
Meu projeto não é JavaScript. Funciona? Sim. Node.js é só o runtime do Conclave. TypeScript, JavaScript, Python e Java têm o grafo completo; outras linguagens têm evidência de diff, escopo e arquivo.
Um achado é intencional. Como silencio?
Adicione conclave-ignore num comentário nessa linha ou na linha de cima, opcionalmente com o nome da regra: // conclave-ignore: discarded-error ou # conclave-ignore unreleased-resource. O achado continua no JSON como nota e deixa de afetar o veredito. Achados bloqueantes não podem ser silenciados assim.
Devo commitar .conclave/?
Não, e você não precisa fazer nada: o Conclave cria .conclave/ com o próprio .gitignore, então o cache local e o histórico nunca aparecem no git status.
PASS significa que posso fazer merge?
Não. Significa que os checks determinísticos não encontraram blocker nem warning. Rode seus testes e peça review a uma pessoa. O Conclave nunca aprova nem faz merge.
Ele corrige os problemas que encontra? Não, de propósito. Ele escreve um prompt de correção para o seu coding agent e confere o resultado.
Qual a diferença de pedir para uma IA revisar meu PR? O veredito vem de regras determinísticas com evidência citada, então a mesma mudança sempre recebe a mesma resposta, e um modelo confiante não consegue convencê-lo a aprovar.
Solução de problemas
| Problema | Solução |
| --- | --- |
| Nothing to review | Não há mudanças contra a base detectada. Informe uma: conclave check . --base origin/main. |
| O mesmo aviso aparece em todo review | Silencie casos intencionais com um comentário conclave-ignore (perguntas frequentes). "Exported behavior changed without a test change" já vira nota em repositórios sem testes. |
| Base errada detectada | Use --base <ref>. Rode git fetch antes se a base for uma branch remota. |
| conclave: command not found | Instale globalmente (npm install -g conclave-ai) ou use npx conclave. |
| Unknown command: check ou outros comandos faltando | Uma instalação global antiga está respondendo. Rode conclave --version e depois npm install -g conclave-ai@latest. |
| Ask diz que falta chave ou modelo | Rode conclave init e depois conclave provider-check. |
| Uma configuração não muda | conclave config mostra de onde vem cada valor; variável do shell ou .env do projeto têm prioridade sobre as configurações do usuário. |
| Porta do cockpit em uso | conclave open . --port 4318 |
| Skill de agente estoura o tempo num repositório grande | Defina CONCLAVE_TIMEOUT_MS=600000 (o padrão é 300000). |
| Qualquer outra coisa | conclave doctor . verifica Git, linguagens, skills e CI. Abra uma issue com a saída dele. |
Documentação
| Guia | Conteúdo | | --- | --- | | CLI | Todos os comandos, opções, configurações, variáveis de ambiente, modelos locais | | Cockpit | Interface no navegador, telas de repositório, auditorias, findings inbox, propostas de issue, Conclaves salvos | | Auditoria de repositório · Fluxo de achados · Descoberta semântica | Auditoria do repositório inteiro, o registro de achados e as propostas, hipóteses de modelo (em inglês) | | Skill de agente | Setup no Claude Code e Codex, prompts, ciclo de correção, MCP | | GitHub Actions | Workflow de pull request e evidências de CI | | Como funciona | Pipeline, linguagens, cobertura, quando vale usar um modelo | | Linhagem de review | Séries de correção, recibos, rebaselines (em inglês) | | Segurança | Limites de confiança e modelo de ameaças (em inglês) | | Changelog · Roadmap | Versões e direção |
Contribuindo
git clone https://github.com/carvalhobfr/conclave-ai.git
cd conclave-ai
npm install
npm run verify # typecheck, lint, build, testes, avaliações, auditIssues e pull requests são bem-vindos. Veja CONTRIBUTING.md.
