Agent-Blackbox - Công cụ quan sát quá trình chạy Claude Code/OpenCode bằng bản đồ phiên và phân tích lãng phí token

Tôi đã tạo ra Agent-Blackbox, một công cụ ghi lại quá trình chạy của Claude Code / OpenCode trên máy cục bộ và hiển thị chúng bằng bản đồ phiên cùng điểm hiệu quả ngữ cảnh.

Có một nghiên cứu cho thấy khi hỏi AI “bạn nghĩ tác vụ này sẽ tốn bao nhiêu token?”, mức tương quan với chi phí thực tế chỉ là 0.39.

https://arxiv.org/abs/2604.22750

Khi chạy Claude Code hoặc OpenCode trong thời gian dài, điều này cho cảm giác là một vấn đề khá thực tế. Phần tóm tắt cuối cùng có vẻ hợp lý, nhưng trên thực tế lại khó lần theo nó đã đọc những tệp nào, lệnh nào đã thất bại, và đã tiêu tốn nhiều token ở đâu.

Thay vì phân tích phần tóm tắt cuối cùng của agent, Agent-Blackbox ghi lại các sự kiện thực tế.

• đọc / chỉnh sửa tệp
• thực thi bash và mã thoát
• tìm kiếm
• cập nhật todo
• yêu cầu quyền
• ủy quyền cho sub-agent, sử dụng skill
• luồng sử dụng model / token
• luồng sửa lỗi / thử lại sau khi thất bại, v.v.

Có thể chạy ngay bằng npx mà không cần cài đặt.

Ghi lại Claude Code:
npx @taewooopark/agent-blackbox up --host claude-code

Ghi lại OpenCode:
npx @taewooopark/agent-blackbox up --host opencode

Ghi lại cả hai:
npx @taewooopark/agent-blackbox up --host all

Claude Code sẽ tail transcript trong ~/.claude/projects mà không cần cài đặt riêng. OpenCode nhận sự kiện qua plugin global. Ghi log cơ bản và dashboard đều chạy cục bộ, không cần API key.

Tôi cũng thêm phân tích hiệu quả ngữ cảnh. Ví dụ, nó phát hiện những trường hợp như sau.

• đọc lặp lại cùng một tệp
• đọc quá nhiều tệp so với lượng chỉnh sửa
• output lớn từ command/tool chiếm quá nhiều ngữ cảnh
• lặp lại lệnh thất bại mà không sửa nguyên nhân
• dùng nhiều token nhưng thay đổi thực tế lại ít
• mức tận dụng prompt cache thấp

Vì hiển thị theo tên tệp hoặc từng lệnh gây ra vấn đề, nên ở lần chạy tiếp theo có thể xem khá cụ thể cần giảm bớt điều gì. Ngoài ra, có thể tùy chọn ghi lại phần lãng phí đã phát hiện vào AGENTS.md hoặc CLAUDE.md dưới dạng khối quản lý, để lần chạy sau ít lặp lại cùng một sai lầm hơn.

Trong một trường hợp tôi chạy lại cùng một tác vụ với cùng model, lượng token sử dụng đã giảm từ 939k -> 521k và điểm hiệu quả tăng từ 80 -> 99. Đây không phải benchmark đã được kiểm chứng lặp lại; mong mọi người xem như một ví dụ cho thấy “có thể phản ánh phần lãng phí quan sát được trong lần chạy thực tế vào vòng lặp tiếp theo”.

Nó đặc biệt phù hợp với các multi-agent harness như oh-my-openagent hoặc oh-my-claudecode. Vì thời gian chạy càng dài thì càng khó kiểm tra bằng mắt xem ai đã chạm vào tệp nào và chỗ nào xuất hiện lặp lại.

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

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

Nếu dùng thử và có phản hồi về những sự kiện muốn thấy thêm trong bản đồ phiên, các chỉ số hiệu quả, hoặc quy trình cài đặt còn bất tiện, rất mong nhận được ý kiến. Xin cảm ơn!

[turtlehwan]

Ồ, nghe thật thú vị! Có vẻ là một ý tưởng hay đấy.

[theoverstructure]

Cảm ơn bạn! Mình cũng đã trau chuốt giao diện thật đẹp mắt, nên nếu bạn dùng thử thì có lẽ sẽ thấy còn thú vị hơn nữa. Thật sự rất cảm ơn những lời tốt đẹp của bạn!!

[theoverstructure]

Tôi đã tạo công cụ này vì đặc biệt trong các lần chạy Claude Code/OpenCode dài hoặc khi làm việc đa tác nhân, tôi muốn có thể nhìn một cái là biết những tệp nào đã bị đọc lặp đi lặp lại / lệnh nào đã thất bại / và token bị thất thoát nhiều ở đâu. Vì hiện tại vẫn là dự án do một mình tôi phát triển nên còn nhiều thiếu sót. Nếu bạn dùng thử và góp ý như “nên hiển thị thêm cả sự kiện này”, “chỉ số hiệu quả này còn hơi mơ hồ”, hoặc “luồng cài đặt/chạy chưa thuận tiện” thì tôi sẽ thật sự rất biết ơn!!