Agent-Blackbox - una herramienta para ver ejecuciones de Claude Code/OpenCode con mapa de sesión y análisis de desperdicio de tokens
(github.com/TaewoooPark)Creé Agent-Blackbox, una herramienta que registra localmente las ejecuciones de Claude Code / OpenCode y las muestra con un mapa de sesión y una puntuación de eficiencia de contexto.
Hubo un estudio donde, al preguntarle a una IA “¿Cuántos tokens crees que usarás para esta tarea?”, la correlación con el costo real fue de apenas 0.39.
https://arxiv.org/abs/2604.22750
Después de dejar corriendo Claude Code u OpenCode durante bastante tiempo, esto se sintió como un problema muy real. El resumen final puede sonar convincente, pero en la práctica es difícil seguir qué archivos leyó, qué comandos fallaron y en qué parte se gastaron muchos tokens.
Agent-Blackbox registra eventos reales en lugar de parsear el resumen final del agente.
- lectura / edición de archivos
- ejecución de bash y código de salida
- búsquedas
- actualizaciones de
todo - solicitudes de permisos
- delegación a subagentes, uso de skills
- flujo de uso de modelo / tokens
- flujo de corrección / reintento después de fallos, etc.
Se puede ejecutar directamente con npx, sin instalación.
Registro de Claude Code:
npx @taewooopark/agent-blackbox up --host claude-code
Registro de OpenCode:
npx @taewooopark/agent-blackbox up --host opencode
Registrar ambos:
npx @taewooopark/agent-blackbox up --host all
Claude Code hace tail del transcript en ~/.claude/projects sin instalación adicional. OpenCode recibe eventos como plugin global. El registro base y el dashboard funcionan localmente y no requieren API key.
También agregué análisis de eficiencia de contexto. Por ejemplo, detecta cosas como estas:
- volver a leer repetidamente el mismo archivo
- leer demasiados archivos en comparación con la cantidad editada
- outputs grandes de command/tool que ocupan mucho contexto
- repetir comandos fallidos sin corregir la causa
- usar muchos tokens pero hacer pocos cambios reales
- bajo aprovechamiento de prompt cache
Como muestra el archivo o comando problemático a ese nivel de detalle, es relativamente fácil ver de forma concreta qué conviene reducir en la siguiente ejecución. De forma opcional, el desperdicio detectado se puede registrar como un bloque de gestión en AGENTS.md o CLAUDE.md, para que la siguiente ejecución repita menos los mismos errores.
En un caso donde volví a ejecutar la misma tarea con el mismo modelo, el uso de tokens bajó de 939k -> 521k y la puntuación de eficiencia subió de 80 -> 99. No es un benchmark validado de forma repetida, así que me gustaría que se tomara solo como un ejemplo de que “es posible reflejar en el siguiente ciclo el desperdicio observado en una ejecución real”.
En particular, funcionó muy bien con arneses multiagente como oh-my-openagent u oh-my-claudecode. Cuanto más larga es la ejecución, más difícil se vuelve comprobar visualmente quién tocó qué archivo y dónde empezaron las repeticiones.
GitHub:
https://github.com/TaewoooPark/Agent-Blackbox
npm:
https://www.npmjs.com/package/@taewooopark/agent-blackbox
Si lo prueban, agradeceré mucho sus comentarios sobre qué otros eventos les gustaría ver en el mapa de sesión, qué métricas de eficiencia serían útiles o si hubo fricción en el flujo de instalación. ¡Gracias!
3 comentarios
¡Oh, está muy curioso! Me parece una muy buena idea.
¡Gracias! También pulí bastante la UI, así que creo que les parecerá aún más interesante cuando lo prueben. ¡De verdad muchas gracias por sus amables palabras!!
Lo hice porque, especialmente en ejecuciones largas de Claude Code/OpenCode o en trabajos con múltiples agentes, quería poder ver de un vistazo qué archivos se leyeron repetidamente, qué comandos fallaron y en qué parte se desperdician muchos tokens. Como todavía lo desarrollé yo solo, le faltan muchas cosas. ¡Si lo prueban y me dejan comentarios como “estaría bueno mostrar también este evento”, “este indicador de eficiencia es ambiguo” o “el flujo de instalación/ejecución es incómodo”, de verdad se los agradecería mucho!