Agent-Blackbox - ferramenta para visualizar execuções do Claude Code/OpenCode com mapa de sessão e análise de desperdício de tokens

Criei o Agent-Blackbox, que registra execuções do Claude Code / OpenCode localmente e as mostra com um mapa de sessão e uma pontuação de eficiência de contexto.

Houve um estudo em que, ao perguntar para uma IA “quanto token você acha que vai gastar nesta tarefa?”, a correlação com o custo real foi de apenas 0,39.

https://arxiv.org/abs/2604.22750

Ao deixar o Claude Code ou o OpenCode rodando por bastante tempo, isso pareceu um problema bem real. O resumo final até parece plausível, mas na prática é difícil acompanhar quais arquivos foram lidos, quais comandos falharam e onde muitos tokens foram gastos.

Em vez de fazer parsing do resumo final do agente, o Agent-Blackbox registra os eventos reais.

• leitura / edição de arquivos
• execução de bash e código de saída
• buscas
• atualização de todo
• solicitações de permissão
• delegação para subagentes, uso de skills
• fluxo de uso de modelo / tokens
• fluxo de correção / nova tentativa após falhas, etc.

Pode ser executado imediatamente com npx, sem instalação.

Registro do Claude Code:
npx @taewooopark/agent-blackbox up --host claude-code

Registro do OpenCode:
npx @taewooopark/agent-blackbox up --host opencode

Registrar ambos:
npx @taewooopark/agent-blackbox up --host all

O Claude Code faz tail do transcript em ~/.claude/projects sem necessidade de instalação separada. O OpenCode recebe eventos por meio de um plugin global. O registro básico e o dashboard funcionam localmente e não exigem API key.

Também adicionei análise de eficiência de contexto. Por exemplo, ela detecta coisas como:

• releitura repetida do mesmo arquivo
• leitura de arquivos demais em relação ao volume de edição
• output grande de command/tool ocupando muito contexto
• repetição de comandos que falharam sem corrigir a causa
• muito gasto de tokens, mas poucas mudanças reais
• baixo aproveitamento de prompt cache

Como mostra em nível de arquivo ou de comando o que causou o problema, dá para ver de forma relativamente concreta o que seria melhor reduzir na próxima execução. Opcionalmente, os desperdícios encontrados podem ser registrados em um bloco de gerenciamento no AGENTS.md ou CLAUDE.md, para que a próxima execução repita menos os mesmos erros.

Em um caso em que executei a mesma tarefa novamente com o mesmo modelo, o uso de tokens caiu de 939k para 521k, e a pontuação de eficiência subiu de 80 para 99. Não é um benchmark validado de forma repetida, então peço que vejam isso mais como um exemplo de que “é possível refletir desperdícios observados em execuções reais no loop seguinte”.

Funcionou especialmente bem com harnesses multiagente como oh-my-openagent e oh-my-claudecode. Quanto mais longa a execução, mais difícil fica verificar visualmente quem mexeu em qual arquivo e onde surgiram repetições.

GitHub:
https://github.com/TaewoooPark/Agent-Blackbox

npm:
https://www.npmjs.com/package/@taewooopark/agent-blackbox

Se testarem, agradeço feedback sobre eventos que vocês gostariam de ver no mapa de sessão, métricas de eficiência e qualquer fluxo de instalação que tenha ficado inconveniente. Obrigado!

[turtlehwan]

Nossa, isso é bem interessante! Parece uma ótima ideia.

[theoverstructure]

Obrigado! Também dei um belo polimento na UI, então acho que você vai achar ainda mais interessante quando usar. Muito obrigado pelas palavras gentis!!

[theoverstructure]

Criei isso porque, especialmente em execuções longas do Claude Code/OpenCode ou em trabalhos com múltiplos agentes, eu queria ver de relance quais arquivos foram lidos repetidamente, quais comandos falharam e onde muitos tokens estão sendo desperdiçados. Como ainda fui eu sozinho que desenvolvi, ainda há vários pontos a melhorar. Se puderem testar e me mandar feedback como “seria bom mostrar este evento também”, “esta métrica de eficiência está meio ambígua” ou “o fluxo de instalação/execução é desconfortável”, eu realmente agradeço!!