Interstat: A Token Efficiency Evaluation Tool Built for Claude Code Agent Workflows

Interstat is an open-source token efficiency evaluation tool designed for Claude Code users. It addresses the pain point of unclear token consumption in agent workflows by providing a double-stage data collection mechanism (real-time event capture + post-session token data backfilling). Key values include quantifying token usage, identifying optimization opportunities, and enabling data-driven cost-benefit decisions for AI agent workflows.

When using Claude Code for complex tasks, agents may create subagents, call tools, or have multi-round dialogues—all consuming tokens. However, Claude Code doesn't expose real-time token counts during sessions, so users can only check total consumption post-session via JSONL logs. This makes it hard to adjust workflows in time, leading to unnecessary costs. Interstat aims to solve this by answering not just 'how many tokens' but also 'where they are used' and 'how to optimize'.

Interstat uses a dual-stage approach:

1. Real-time event capture: During sessions, it uses PostToolUse:Task hooks to capture tool usage, subagent creation, and event sequences, storing these in an SQLite database (WAL mode for concurrency).
2. Token data backfilling: After session ends, SessionEnd hook parses JSONL logs to extract exact token counts and completes database records. This combines structural event data with accurate token metrics for complete analysis.

As a Claude Code plugin, Interstat offers three main commands:

• /interstat:interstat-report: Generates a full report with percentile analysis and decision gates to assess token efficiency levels.
• /interstat:interstat-status: Provides real-time session metrics (event structure and progress, no live token counts due to Claude Code limitations).
• /interstat:interstat-analyze: Deep usage pattern analysis to identify token consumption trends and optimization opportunities (e.g., redundant subagent calls).

Architecture: Data is stored in an SQLite database at ~/.claude/interstat/metrics.db (Schema v2, with bead_id for traceable work units and phase for stage-based analysis). A cross-layer interface scripts/cost-query.sh supports multiple query modes (aggregate, by-bead, cost-usd, baseline, etc.) outputting JSON. Ecosystem: Integrates with interagency-marketplace (install via commands) and complements intersearch (handles session search/context export while Interstat focuses on token metrics).

Interstat's value spans multiple scenarios:

• Personal developers: Get feedback on usage habits to build more efficient agent interactions.
• Teams: Benchmark cost-effectiveness of different development practices.
• Organizations: Measure ROI of AI-assisted development (e.g., compare token costs vs code quality changes when introducing Claude Code in CI/CD). Examples: Identify tasks with excessive subagent usage to optimize prompts/workflows.

Limitations: Currently Claude Code-specific (relies on its extension points), so needs adaptation for other AI tools; requires users to translate analysis results into actionable optimizations. Future: As AI coding assistants become mainstream, token efficiency tools like Interstat may become standard. The dual-stage design and North Star metric (cost-per-landable-change) provide a reference for the field; future versions may support more AI platforms and offer more actionable optimization suggestions.