Pular para o conteúdo principal
Um diff mostra o que mudou. O recurso Kodus Trace guarda o porquê. Ele captura as sessões de agentes de código em um repositório, transforma a branch que você envia em decisões (escolhas de arquitetura, convenções, tradeoffs) e permite que você ou um agente leia as decisões registradas para um caminho antes de alterá-lo. A captura e a consulta locais funcionam pelo CLI. O uso de decisões do Trace com dados sensíveis ocultados como contexto em reviews de PR está em alpha privado na Kodus Cloud, para o mesmo repositório.

Ative

Execute dentro do repositório. Ele instala:
  • Hooks de sessão para o Claude Code (o .claude/settings.json do repositório), o Cursor (o .cursor/hooks.json do repositório) e o Codex (~/.codex/config.toml, na sua pasta pessoal). --agents claude,cursor limita quais, e --codex-config <path> aponta para outra configuração do Codex.
  • Dois hooks do git. prepare-commit-msg adiciona um trailer Kodus-Trace: a cada mensagem de commit, ligando o commit à sua sessão. pre-push inicia a destilação em segundo plano.
  • Uma configuração de fetch para que um simples git fetch também traga as decisões compartilhadas.
O hook pre-push divide o arquivo com o hook de revisão de kodus hook install. Com os dois instalados, um push não inicia a destilação, então nenhuma decisão nova é gravada. kodus hook uninstall remove apenas o hook de revisão e mantém o do Trace.
Confira o que ele fez com kodus trace status: sessões e turnos capturados, decisões (locais e compartilhadas), hooks instalados e qualquer problema encontrado. Remova os hooks com kodus trace disable (adicione --dry-run para ver uma prévia). Desativar remove apenas os hooks: as sessões capturadas ficam na sua máquina, e os eventos já enviados à Kodus continuam lá.

O que é capturado

Cada turno de uma sessão de agente: o prompt e a resposta, um resumo de uma linha de cada ferramenta que o agente usou, os arquivos que leu e alterou, seus comandos e o uso de tokens. Os registros ficam em ~/.kodus/sessions, fora do repositório, e são apagados após 90 dias. Antes de salvar ou enviar eventos, o CLI mascara os padrões de segredo que reconhece. O conteúdo capturado ainda pode conter dados sensíveis. Mantenha credenciais fora das sessões que você captura. Para parar de capturar novas sessões, rode kodus trace disable. A captura funciona sem conta. Quando você entra com sua conta ou com uma chave de equipe, o CLI mascara os segredos que reconhece e envia à Kodus os eventos de cada sessão: os prompts e respostas, as ferramentas que o agente chamou com suas entradas e saídas, os arquivos lidos e alterados, os comandos, o uso de tokens, a branch, a URL do remote git e os ids dos commits. A Kodus os armazena para a sua organização. Quando uma sessão termina, um modelo os lê para extrair decisões, usando o modelo BYOK da sua organização quando ela tem um e um modelo gerenciado pela Kodus caso contrário. Esses eventos contam para as 1.000 requisições por hora da equipe.

Como as decisões são geradas

No git push, um job em segundo plano resume cada commit da sua branch que não está na branch padrão. Em seguida, ele pede a um CLI de agente de código na sua máquina que transforme esses resumos e as sessões capturadas da branch em decisões. Usa o primeiro entre claude, codex, gemini e cursor-agent que encontrar. Essa ferramenta recebe as mensagens de commit, os nomes dos arquivos e os prompts e respostas das sessões já sem segredos, então eles vão para o provedor dela como em qualquer outro uso. Sem nenhuma delas instalada, a captura continua funcionando e nenhuma decisão é gravada. O job nunca atrasa nem faz um push falhar. Ele grava as decisões em uma branch chamada kodus/trace/v1 e envia essa branch para o mesmo remote, então o clone de um colega as recebe com git fetch. Cada push substitui o registro dessa branch.

Leia as decisões

Passe os caminhos que você está prestes a alterar. Nenhum subcomando é necessário.
Um diretório retorna tudo o que foi registrado dentro dele. Um arquivo retorna tudo cujo escopo o cobre, inclusive decisões registradas para o diretório dele. A leitura usa o que já está na sua máquina e não faz nenhuma chamada de rede. --remote <name> escolhe o remote cuja branch de decisões será lida. Cada decisão mostra:
  • Type: architectural_decision, convention, tradeoff, implementation_detail, tooling ou other.
  • Origin: human se você pediu, agent se o agente escolheu por conta própria, collaborative se vocês decidiram juntos.
  • Confidence, de 0 a 1, conforme avaliada quando a decisão foi escrita.
  • Scope, os caminhos aos quais se aplica, e a source: local (registrada aqui) ou branch (compartilhada por outra pessoa).
  • Um id, a referência usada por forget e pin.
Um resultado vazio é uma resposta normal, com código de saída 0. Significa que nada foi registrado para esses caminhos ainda, ou que a captura está desligada. Se um caminho tiver o nome de um subcomando, como status, separe-o com --: kodus trace -- status.

Corrija o registro

Ambos são salvos localmente. Quando a decisão está na branch compartilhada, também são publicados nela, para que a equipe veja a correção.
Serve suas sessões locais no navegador. Lê apenas o armazenamento local.

Variáveis de ambiente

Relacionados

Agentes de IA

Skills e loops para agentes de código.

Referência de Comandos

Todos os comandos kodus trace.