Where your tokens go

Your AI agent consumes tokens and you don't know where. token-report.shreads Claude Code's session logs and breaks it down.

What it shows

  • Per-session token breakdown— input, cache creation, cache read, and output counts for every session.
  • Per-subagent breakdown— which Agent tool spawns consumed the most tokens during a session.
  • Cost estimation with cache-aware pricing. Reads are billed at 10% of input, cache creation at 125% of input.
  • Cache efficiency metric: cache_read / (cache_read + cache_creation). High values mean the session reused context instead of rebuilding it.

Usage

bin/token-report.sh                    # current project
bin/token-report.sh --all              # all projects
bin/token-report.sh --since 7d         # last 7 days
bin/token-report.sh --subagents        # per-subagent breakdown
bin/token-report.sh --check            # anomaly detection
bin/token-report.sh --json             # machine-readable

Anomaly detection

token-report.sh --check flags:

  • Sessions that used more than 3x the average tokens (possible loop).
  • Single subagents consuming more than 60% of session tokens.
  • Unusual session frequency (more than 4x the average per hour).

Run it after a long autopilot sprint to catch runaway agents before they burn the budget.

Integration with analytics

Token data merges into the main analytics report:

bin/analytics.sh --tokens              # merge token data into analytics

This lets you correlate token spend with phase duration, finding counts, and sprint outcomes.

Claude Code only

Token analysis reads the JSONL session logs that Claude Code writes under ~/.claude/projects/. On other agents (Cursor, Codex, OpenCode, Gemini CLI), the command skips gracefully with no error. You can still use every other script in nanostack; you just won't get token breakdowns until you run the same project through Claude Code.

Previous← KnowledgeNextIntensity modes →