Agent-Blackbox - सेशन मैप और टोकन वेस्ट विश्लेषण के साथ Claude Code/OpenCode रन देखने का टूल

मैंने Agent-Blackbox बनाया है, जो Claude Code / OpenCode के रन को लोकल में रिकॉर्ड करता है और उन्हें सेशन मैप व context efficiency score के साथ दिखाता है.

एक शोध में पाया गया कि अगर AI से पूछा जाए, “इस काम में तुम कितने टोकन खर्च होने का अनुमान लगाते हो?”, तो वास्तविक लागत से उसका सहसंबंध केवल 0.39 होता है.

https://arxiv.org/abs/2604.22750

Claude Code या OpenCode को लंबे समय तक चलाने पर यह काफ़ी वास्तविक समस्या लगने लगी. आख़िरी summary देखने में ठीक लगती है, लेकिन असल में कौन-सी files पढ़ी गईं, कौन-से commands fail हुए, और कहाँ सबसे ज़्यादा टोकन खर्च हुए, यह ट्रैक करना मुश्किल था.

Agent-Blackbox एजेंट की आख़िरी summary को parse करने के बजाय, वास्तविक events को रिकॉर्ड करता है.

• file read / edit
• bash execution और exit code
• search
• todo update
• permission request
• sub-agent delegation, skill usage
• model / token usage flow
• fail होने के बाद fix / retry flow आदि

इसे बिना install किए सीधे 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 बिना किसी अलग install के ~/.claude/projects transcript को tail करता है. OpenCode global plugin के रूप में events प्राप्त करता है. डिफ़ॉल्ट रिकॉर्डिंग और dashboard लोकल में चलते हैं, और किसी API key की ज़रूरत नहीं होती.

मैंने context efficiency analysis भी जोड़ा है. उदाहरण के लिए, यह ऐसी चीज़ें पकड़ता है.

• एक ही file को बार-बार दोबारा पढ़ना
• edit की मात्रा की तुलना में बहुत ज़्यादा files पढ़ना
• बड़ा command/tool output context में बहुत जगह घेरना
• कारण ठीक किए बिना failed command को दोहराना
• बहुत टोकन खर्च हुए, लेकिन वास्तविक बदलाव कम रहे
• prompt cache का कम उपयोग

क्योंकि यह समस्या पैदा करने वाली file या command यूनिट के हिसाब से दिखाता है, इसलिए अगली run में क्या कम करना चाहिए, यह काफ़ी ठोस तरीके से देखा जा सकता है. वैकल्पिक रूप से, मिले हुए waste को AGENTS.md या CLAUDE.md में management block के रूप में लिखकर रखा जा सकता है, ताकि अगली run में वही गलतियाँ कम दोहराई जाएँ.

एक मामले में, जहाँ मैंने उसी काम को उसी model के साथ फिर से चलाया, token usage 939k -> 521k तक घट गई और efficiency score 80 -> 99 तक बढ़ गया. यह बार-बार सत्यापित किया गया benchmark नहीं है; इसे बस ऐसे उदाहरण की तरह देखें कि “वास्तविक रन में देखे गए waste को अगले loop में reflect करने का तरीका संभव है.”

खास तौर पर यह oh-my-openagent या oh-my-claudecode जैसे multi-agent harness के साथ अच्छी तरह जंचा. क्योंकि run जितनी लंबी होती है, यह आँखों से समझना उतना ही मुश्किल हो जाता है कि किसने कौन-सी file बदली और कहाँ repetition हुई.

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

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

इसे इस्तेमाल करके देखें, और अगर सेशन मैप में आप कोई और event, efficiency metric, या install flow से जुड़ी कोई असुविधा देखना चाहें, तो feedback ज़रूर दें. धन्यवाद!

[turtlehwan]

ओह, यह काफ़ी दिलचस्प है! मुझे लगता है कि यह एक अच्छा आइडिया है।

[theoverstructure]

धन्यवाद! हमने UI को भी काफी निखारा है, इसलिए अगर आप इसे इस्तेमाल करके देखें तो शायद यह आपको और भी दिलचस्प लगे। आपके अच्छे शब्दों के लिए सच में बहुत-बहुत धन्यवाद!!

[theoverstructure]

खासकर लंबे Claude Code/OpenCode रन या multi-agent काम में, कौन-सी फ़ाइलें बार-बार पढ़ी गईं / कौन-से कमांड फेल हुए / कहाँ टोकन सबसे ज़्यादा बर्बाद हो रहे हैं, यह एक नज़र में देखने के लिए मैंने इसे बनाया है। अभी इसे मैंने अकेले डेवलप किया है, इसलिए कमियाँ काफ़ी हैं। आप इसे इस्तेमाल करके अगर “यह event भी दिखे तो अच्छा होगा”, “यह efficiency metric थोड़ा अस्पष्ट है”, “install/execute flow असुविधाजनक है” जैसी feedback दें, तो मैं सच में बहुत आभारी रहूँगा!!