Agent-Blackbox - Claude Code/OpenCode çalıştırmalarını oturum haritası ve token israfı analiziyle görselleştiren araç

Claude Code / OpenCode çalıştırmalarını yerelde kaydedip bunları oturum haritası ve bağlam verimliliği puanıyla gösteren Agent-Blackbox’ı geliştirdim.

Yapay zekaya “Bu iş için ne kadar token harcayacağını düşünüyorsun?” diye sorulduğunda, gerçek maliyetle korelasyonunun yalnızca 0.39 olduğunu gösteren bir araştırma vardı.

https://arxiv.org/abs/2604.22750

Claude Code veya OpenCode’u uzun süre çalıştırdığınızda bunun oldukça gerçek bir sorun gibi hissettirdiğini fark ettim. Son özet kulağa makul geliyor, ama gerçekte hangi dosyaların okunduğunu, hangi komutların başarısız olduğunu ve tokenların nerede fazla harcandığını takip etmek zor oluyor.

Agent-Blackbox, ajanın son özetini parse etmek yerine gerçek olayları kaydeder.

• dosya okuma / düzenleme
• bash çalıştırma ve çıkış kodu
• arama
• todo güncellemeleri
• izin istekleri
• alt ajan devri, beceri kullanımı
• model / token kullanım akışı
• başarısızlıktan sonra düzeltme / yeniden deneme akışı vb.

Kurulum gerektirmeden doğrudan npx ile çalıştırabilirsiniz.

Claude Code kaydı:
npx @taewooopark/agent-blackbox up --host claude-code

OpenCode kaydı:
npx @taewooopark/agent-blackbox up --host opencode

İkisini de kaydetme:
npx @taewooopark/agent-blackbox up --host all

Claude Code, ek kurulum olmadan ~/.claude/projects altındaki transcript’i tail eder. OpenCode ise olayları global bir eklenti üzerinden alır. Varsayılan kayıt ve pano yerelde çalışır; API key gerekmez.

Bağlam verimliliği analizini de ekledim. Örneğin şunları yakalar:

• aynı dosyayı tekrar tekrar yeniden okuma
• yapılan düzenleme miktarına kıyasla çok fazla dosya okuma
• büyük command/tool çıktılarının bağlamda fazla yer kaplaması
• başarısız komutları, nedeni düzeltilmeden tekrar etme
• çok token harcanmasına rağmen gerçek değişikliğin az olması
• prompt cache kullanımının düşük olması

Sorunlu dosya adları veya komut bazında gösterdiği için, bir sonraki çalıştırmada neyi azaltmanın iyi olacağını nispeten somut şekilde görebilirsiniz. İsteğe bağlı olarak tespit edilen israfı AGENTS.md veya CLAUDE.md içine yönetim bloğu olarak yazdırarak, sonraki çalıştırmanın aynı hataları daha az tekrarlamasını sağlayabilirsiniz.

Aynı işi aynı modelle tekrar çalıştırdığım bir örnekte token kullanımı 939k -> 521k seviyesine düştü ve verimlilik puanı 80 -> 99’a çıktı. Bu, tekrar tekrar doğrulanmış bir benchmark değil; daha çok “gerçek çalıştırmada gözlemlenen israfı sonraki döngüye yansıtma yaklaşımı mümkün” türünde bir örnek olarak görülürse sevinirim.

Özellikle oh-my-openagent veya oh-my-claudecode gibi çoklu ajan harness’leriyle iyi uyum sağladı. Çünkü çalıştırma uzadıkça kimin hangi dosyaya dokunduğunu ve tekrarların nerede oluştuğunu gözle takip etmek zorlaşıyor.

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

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

Deneyip oturum haritasında görmek istediğiniz başka olaylar, verimlilik metrikleri veya rahatsız edici kurulum akışları varsa lütfen geri bildirim paylaşın. Teşekkürler!

[turtlehwan]

Vay, gerçekten çok ilginçmiş! Bence harika bir fikir gibi görünüyor.

[theoverstructure]

Teşekkür ederim! Arayüzü de şık bir şekilde elden geçirdim; denerseniz muhtemelen size daha da ilgi çekici gelecektir. Güzel sözleriniz için gerçekten çok teşekkürler!!

[theoverstructure]

Özellikle uzun Claude Code/OpenCode çalıştırmaları ya da çoklu ajan görevlerinde, hangi dosyaların tekrar tekrar okunduğunu / hangi komutların başarısız olduğunu / tokenların nerede çok harcandığını tek bakışta görebilmek için bunu yaptım. Hâlâ tek başıma geliştirdiğim için eksikleri çok. Deneyip “bu olayı da gösterse iyi olur”, “bu verimlilik metriği belirsiz kalıyor”, “kurulum/çalıştırma akışı kullanışsız” gibi geri bildirimler verirseniz gerçekten çok sevinirim!!