Solução de Problemas

Inicie qualquer investigação com:

kodus status
kodus auth status
kodus review --verbose    # ou qualquer comando com --verbose

kodus status mostra o estado consolidado (modo de autenticação, org, repositório, hook, versão). --verbose imprime a URL de API resolvida e detalhes por requisição.

Erros Comuns

Comando não encontrado: kodus

O CLI não está no seu PATH. Reinstale com a flag global do seu gerenciador de pacotes, ou use npx @kodus/cli <command> para execuções avulsas.

npm install -g @kodus/cli
yarn global add @kodus/cli
pnpm add -g @kodus/cli
bun add -g @kodus/cli

Se você instalou via o instalador de skills, re-execute curl -fsSL https://review-skill.com/install | bash para corrigir as entradas do PATH.

AUTH_REQUIRED ou 401 Unauthorized

Execute kodus auth status para ver o modo atual.
Se estiver usando uma chave de equipe, verifique se ainda está ativa em app.kodus.io/organization/cli-keys.
Se estiver usando login pessoal, tente kodus auth login novamente — o token de refresh pode ter expirado.
Para CI, confirme que KODUS_TOKEN (ou KODUS_TEAM_KEY) está definido no ambiente em que o pipeline é executado.
Se self-hosted, confirme que KODUS_API_URL aponta para a instância correta.

NOT_IN_GIT_REPO

kodus review requer um diretório de trabalho git. Navegue (cd) até um repositório ou inicialize um com git init. Para comandos kodus config repo, você pode passar owner/repo explicitamente em vez de ..

A revisão demora muito ou parece travar

Branches grandes (centenas de arquivos, milhares de linhas) podem levar vários minutos. O timeout padrão de requisição é de 60 minutos — você deve ver progresso no modo verbose.

Use --verbose para confirmar que a requisição está em andamento.
Para diffs muito grandes, prefira --branch <base> ou --commit <sha> em vez do modo de árvore de trabalho: eles permitem que o backend clone o mesmo commit em vez de receber conteúdo de arquivo inline.
Substitua o timeout com KODUS_REQUEST_TIMEOUT_MIN=90 kodus review se necessário.
Divida o trabalho em branches menores quando possível.

Arquivos estão sendo ignorados na revisão

A revisão respeita os padrões ignore-files configurados em kodus config repo. Liste as configurações atuais com:

kodus config repo show

Você pode adicionar ou remover padrões:

kodus config repo add-ignore-file . "**/*.generated.ts"
kodus config repo remove-ignore-file . "**/*.generated.ts"

Arquivos binários, imagens e lockfiles são ignorados por padrão.

Limite de taxa atingido / Trial esgotado

O modo trial permite 5 revisões por dia. Faça login com kodus auth login ou configure uma chave de equipe via kodus auth team-key --key kodus_xxxxx para aumentar os limites. kodus auth status exibe seu uso atual.

API retornou resposta inválida (esperava JSON, recebeu HTML)

Seu KODUS_API_URL está atingindo um proxy reverso ou página do Cloudflare Access em vez da API. Verifique:

O caminho da URL (sem /api, /v1 extras, etc.).
Credenciais do Cloudflare Access (CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET) se aplicável.
Que o proxy encaminha os headers Authorization e CF-Access-* intactos.

HTTPS obrigatório para URL da API

O CLI rejeita URLs de API não-HTTPS para tudo, exceto localhost e 127.0.0.1. Provisione um certificado TLS válido para sua instância self-hosted, ou use http://localhost:<porta> para desenvolvimento local.

O hook pre-push não está sendo executado

Confirme a instalação: kodus hook status.
Certifique-se de que .git/hooks/pre-push é executável.
Outros gerenciadores de hook (Husky, Lefthook, pre-commit) podem sobrescrever .git/hooks/pre-push. Encadeie-os ou reinstale com kodus hook install --force.
Ignore o hook para um único push: KODUS_SKIP_HOOK=1 git push.

Os hooks de decisions (memória) não estão capturando

Execute kodus decisions status para ver quais agentes estão configurados.
Re-execute kodus decisions enable --force para reinstalar os arquivos de integração.
Para Codex, certifique-se de que ~/.codex/config.toml contém a linha notify = ["kodus", "decisions", "capture", ...], ou passe --codex-config <path>.
Verifique se o agente realmente emite eventos de turno completo (algumas configurações mais antigas do Claude Code não emitem).

Limite de dispositivos atingido

Instâncias self-hosted podem impor limites de dispositivos por organização. Peça ao seu administrador para aumentar o limite ou remover dispositivos não utilizados do painel.

Códigos de Saída

Use-os em scripts e pipelines de CI.

Código	Significado
`0`	Sucesso. Nenhum problema encontrado, ou problemas encontrados mas abaixo de `--fail-on`.
`1`	Problemas encontrados na severidade `--fail-on` ou acima.
`2`	Erro de uso do CLI (flag inválida, argumento ausente).
`3`	Falha de autenticação ou autorização.
`4`	Erro de rede ou API (timeout, 5xx, resposta inválida).
`5`	Não está em um repositório git, ou não há alterações para revisar.

Para CI, combine --fail-on error com --format json e --output review.json para expor resultados estruturados como artefatos do pipeline sem afetar a lógica de código de saída.

Dicas de Depuração

--verbose em qualquer comando imprime a URL de API resolvida, IDs de requisição e timings.
kodus schema exibe o esquema de comandos legível por máquina — útil quando seu agente reporta uma flag ausente.
--agent força saída determinística e legível por máquina; combine com --format json ao criar scripts.
KODUS_VERBOSE=true mantém o modo verbose em múltiplos comandos durante uma sessão.

Obtendo Ajuda

Reportar bugs: github.com/kodustech/cli/issues
Solicitações de funcionalidades, dúvidas de configuração: seu gerente de conta Kodus, ou support@kodus.io.
Para implantações self-hosted, inclua a saída de kodus status --verbose ao abrir um issue.

Primeiros Passos

Cobrança e Licenças

Revisão de Código com IA

CLI

Cockpit

Kody Issues

Organização

Segurança