Agent-Blackbox - Claude Code/OpenCode の実行をセッションマップとトークン浪費分析で可視化するツール
(github.com/TaewoooPark)Claude Code / OpenCode の実行をローカルで記録し、セッションマップとコンテキスト効率スコアで表示する Agent-Blackbox を作りました。
AI に「この作業にどれくらいトークンを使いそう？」と尋ねると、実際のコストとの相関関係が 0.39 に過ぎないという研究がありました。
https://arxiv.org/abs/2604.22750
Claude Code や OpenCode を長時間回していると、これはかなり現実的な問題だと感じました。最後の要約はもっともらしくても、実際にはどのファイルを読んだのか、どのコマンドが失敗したのか、どこでトークンを多く使ったのかを追いかけるのが難しかったです。
Agent-Blackbox はエージェントの最後の要約をパースする代わりに、実際のイベントを記録します。
- ファイルの読み取り / 修正
- bash の実行と終了コード
- 検索
- todo の更新
- 権限リクエスト
- サブエージェントへの委任、スキル使用
- モデル / トークン使用の流れ
- 失敗後の修正 / 再試行の流れ など
インストール不要で npx ですぐ実行できます。
Claude Code の記録:
npx @taewooopark/agent-blackbox up --host claude-code
OpenCode の記録:
npx @taewooopark/agent-blackbox up --host opencode
両方を記録:
npx @taewooopark/agent-blackbox up --host all
Claude Code は追加インストールなしで ~/.claude/projects の transcript を tail します。OpenCode はグローバルプラグインとしてイベントを受け取ります。基本的な記録とダッシュボードはローカルで動作し、API key は不要です。
コンテキスト効率分析も入れました。たとえば次のようなものを検出します。
- 同じファイルを繰り返し再読している
- 修正量に比べて読んでいるファイルが多すぎる
- 大きな command/tool output がコンテキストを大きく占有している
- 失敗したコマンドを、原因を直さないまま繰り返している
- トークンは多く使ったのに、実際の変更は少ない
- prompt cache の活用が低い
問題になったファイル名やコマンド単位で表示するため、次の実行で何を減らせばよいかを比較的具体的に見られます。オプションとしては、見つかった浪費を AGENTS.md または CLAUDE.md に管理ブロックとして記録し、次の実行で同じミスを繰り返しにくくすることもできます。
私が同じ作業を同じモデルで再実行してみたあるケースでは、トークン使用量が 939k -> 521k に減り、効率スコアが 80 -> 99 に上がりました。繰り返し検証されたベンチマークではなく、「実行中に観測された浪費を次のループに反映するやり方が可能だ」という程度の事例として見ていただければと思います。
特に oh-my-openagent や oh-my-claudecode のようなマルチエージェントハーネスと相性が良かったです。実行が長くなるほど、誰がどのファイルを触ったのか、どこで繰り返しが発生したのかを目で確認しにくくなるためです。
GitHub:
https://github.com/TaewoooPark/Agent-Blackbox
npm:
https://www.npmjs.com/package/@taewooopark/agent-blackbox
使ってみて、セッションマップでもっと見たいイベント、効率指標、不便なインストールフローがあれば、ぜひフィードバックをお願いします。ありがとうございます！
3件のコメント
おお、すごく興味深いですね！ 良いアイデアだと思います
ありがとうございます！ UIもきれいに磨き上げてみましたので、使ってみるとさらに面白いと感じていただけると思います。温かいお言葉、本当にありがとうございます！！
特に長い Claude Code/OpenCode の実行やマルチエージェント作業で、どのファイルを繰り返し読んだのか / どのコマンドが失敗したのか / どこでトークンが多く無駄になっているのかを一目で見たくて作りました。まだ一人で開発しているため至らない点も多いです。使ってみて、「このイベントも表示されるといい」「この効率指標は微妙だ」「インストール/実行の流れが使いにくい」といったフィードバックをいただけると本当にありがたいです!!