Agent-Blackbox - เครื่องมือสำหรับดูการทำงานของ Claude Code/OpenCode ผ่านแผนที่เซสชันและการวิเคราะห์การสิ้นเปลืองโทเค็น

ผมได้สร้าง Agent-Blackbox ขึ้นมา เพื่อบันทึกการทำงานของ Claude Code / OpenCode บนเครื่องโลคัล และแสดงผลเป็นแผนที่เซสชันกับคะแนนประสิทธิภาพของคอนเท็กซ์

มีงานวิจัยที่พบว่า ถ้าถาม AI ว่า “งานนี้น่าจะใช้โทเค็นเท่าไร?” ความสัมพันธ์กับต้นทุนจริงมีค่าเพียง 0.39 เท่านั้น

https://arxiv.org/abs/2604.22750

พอใช้งาน Claude Code หรือ OpenCode ต่อเนื่องนาน ๆ ก็รู้สึกได้ว่านี่เป็นปัญหาที่สมจริงพอสมควร แม้สรุปตอนท้ายจะดูน่าเชื่อถือ แต่ในความเป็นจริงกลับตามยากว่าอ่านไฟล์ไหนไปบ้าง คำสั่งไหนล้มเหลว และใช้โทเค็นมากตรงไหน

Agent-Blackbox ไม่ได้พาร์สสรุปสุดท้ายของเอเจนต์ แต่บันทึกเหตุการณ์จริงที่เกิดขึ้น

• การอ่าน / แก้ไขไฟล์
• การรัน bash และ exit code
• การค้นหา
• การอัปเดต todo
• การขอสิทธิ์
• การมอบหมายให้ sub-agent, การใช้สกิล
• การไหลของการใช้โมเดล / โทเค็น
• การแก้ไข / ลองใหม่หลังความล้มเหลว เป็นต้น

สามารถรันได้ทันทีด้วย 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 จะ tail transcript ใน ~/.claude/projects โดยไม่ต้องติดตั้งอะไรเพิ่ม ส่วน OpenCode จะรับเหตุการณ์ผ่าน global plugin ระบบบันทึกพื้นฐานและแดชบอร์ดทำงานบนเครื่องโลคัล และไม่ต้องใช้ API key

ผมยังใส่การวิเคราะห์ประสิทธิภาพของคอนเท็กซ์เข้าไปด้วย ตัวอย่างเช่นตรวจจับสิ่งเหล่านี้ได้

• อ่านไฟล์เดิมซ้ำไปซ้ำมา
• อ่านไฟล์มากเกินไปเมื่อเทียบกับปริมาณที่แก้ไข
• command/tool output ขนาดใหญ่กินพื้นที่คอนเท็กซ์มาก
• รันคำสั่งที่ล้มเหลวซ้ำโดยไม่แก้ต้นเหตุ
• ใช้โทเค็นมาก แต่การเปลี่ยนแปลงจริงมีน้อย
• ใช้ prompt cache ได้น้อย

เพราะแสดงให้ดูในระดับชื่อไฟล์หรือคำสั่งที่เป็นปัญหา จึงช่วยให้เห็นค่อนข้างชัดว่าในการรันครั้งถัดไปควรลดอะไรลงบ้าง อีกทางหนึ่งคือสามารถบันทึกสิ่งที่พบว่าเปลืองไว้ในบล็อกจัดการของ AGENTS.md หรือ CLAUDE.md แบบเลือกใช้ได้ เพื่อให้การรันครั้งต่อไปทำพลาดแบบเดิมซ้ำน้อยลง

ในกรณีหนึ่งที่ผมลองรันงานเดิมด้วยโมเดลเดิมอีกครั้ง ปริมาณการใช้โทเค็นลดลงจาก 939k -> 521k และคะแนนประสิทธิภาพเพิ่มจาก 80 -> 99 นี่ไม่ใช่ benchmark ที่ผ่านการตรวจสอบซ้ำอย่างเป็นระบบ แต่ขอให้มองเป็นตัวอย่างว่า “แนวทางนำความสิ้นเปลืองที่สังเกตได้จากการรันจริงไปสะท้อนกลับในลูปถัดไป” นั้นทำได้จริง

โดยเฉพาะมันเข้ากันได้ดีกับ multi-agent harness อย่าง oh-my-openagent หรือ oh-my-claudecode เพราะยิ่งรันนาน ก็ยิ่งมองด้วยตายากว่าใครไปแตะไฟล์ไหน และเกิดการวนซ้ำตรงไหนบ้าง

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

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

ลองใช้งานดูได้เลยครับ และถ้ามีอีเวนต์ที่อยากเห็นเพิ่มในแผนที่เซสชัน ตัวชี้วัดประสิทธิภาพ หรือขั้นตอนติดตั้งที่ยังไม่สะดวก ฝากส่งฟีดแบ็กด้วย ขอบคุณครับ!

[turtlehwan]

โอ้ น่าสนใจมากเลยครับ! ดูเป็นไอเดียที่ดีมากครับ

[theoverstructure]

ขอบคุณครับ! ผมลองขัดเกลา UI ให้ดูดีขึ้นด้วยแล้ว ถ้าได้ลองใช้ น่าจะรู้สึกว่าน่าสนใจยิ่งขึ้นครับ ขอบคุณมากจริง ๆ สำหรับคำพูดดี ๆ!!

[theoverstructure]

ผมทำสิ่งนี้ขึ้นมาเพราะโดยเฉพาะเวลารัน Claude Code/OpenCode ยาว ๆ หรือทำงานแบบมัลติเอเจนต์ ผมอยากเห็นได้ในภาพเดียวว่าไฟล์ไหนถูกอ่านซ้ำ ๆ / คำสั่งไหนล้มเหลว / โทเคนรั่วเปลืองหนักตรงไหน ตอนนี้ยังเป็นงานที่ผมพัฒนาคนเดียวเลยยังมีจุดที่ขาดอยู่อีกมาก ถ้าได้ลองใช้แล้วช่วยส่งฟีดแบ็กอย่าง “อยากให้แสดงอีเวนต์นี้ด้วย”, “ตัวชี้วัดประสิทธิภาพนี้ยังไม่ค่อยชัด”, “ขั้นตอนติดตั้ง/การรันใช้งานไม่สะดวก” แบบนี้มาให้ จะขอบคุณมากจริง ๆ ครับ!!