token-reporter

token-reporter

A Claude Code plugin that displays per-operation token usage when agents and subagents complete. Only outputs in debug mode (claude --debug). Tracks Claude Code 2.1.85–2.1.108.

What it reports

After each Claude Code response (in debug mode), a compact unicode-bordered report appears in the terminal showing:

• Token counts — fresh input + cache-write (what counts toward rate limits) and output
• Cache breakdown — cache-write (included in limits) and cache-read (excluded) shown separately
• Cache efficiency — percentage of total input that came from cache
• Cache invalidation detection — detects and flags cache busts with cause classification:
  • TTL expiry ("hey!" effect — idle >5 min, millions of tokens burned on resume)
  • File change (Edit/Write triggers loadChangedFiles())
  • Bash side effect (linter/formatter modifies files → file watcher invalidates)
  • External change (file watcher detects non-Claude modifications)
  • Penalty cost and batching opportunity analysis
• Compact boundary markers — v2.1.90 ground-truth system/compact_boundary events with preTokens from auto-compaction
• CLAUDE.md / rule reloads — v2.1.101 InstructionsLoaded events, broken down by load_reason (session_start, nested_traversal, path_glob_match, include, compact) with red warning for compact-triggered reloads
• PostCompact / PermissionDenied / TaskCreated — v2.1.90+ lifecycle events rolled into the next Stop report
• tool-results/ spillover — v2.1.90 large tool outputs spilled to ~/.claude/projects/<project>/<session>/tool-results/ are credited to the originating tool
• Worktree sub-agent breakdown — dedicated box showing per-agent cache dynamics when skills spawn agent swarms in worktrees
• Duration — elapsed time from first to last message in the operation
• Per-tool attribution — input, output, and result tokens for each tool used
• Per-skill attribution — v2.1.108+ built-in slash commands route through the Skill tool. Each skill invocation shows invocation count, result→input bytes (the skill content loaded into context), output bytes, and an estimated cost per skill. Skills are sorted by cost so the biggest drains float to the top
• Sub-agent aggregation by type — when the same agent type is spawned multiple times (e.g. Explore x5), an aggregated row shows the total count, tokens, and cost per type in addition to the individual per-instance drill-down
• Standalone Skills box (opt-in via SKILLS_BOX) — when enabled, the per-skill breakdown is rendered in its own dedicated unicode box instead of as an inline section in the main report
• Per-section truncation (MAX_ENTRIES_PER_SECTION, default 12) — long lists (skills, bash, web, files, sub-agents) are capped to keep inline output under Claude Code's hook output limit, with a ⋯ +N more — see HTML report indicator
• Full HTML report (always on in debug mode) — every Stop/SubagentStop event writes a self-contained nicely-formatted HTML file to <main-repo-root>/reports/token-reporter/<YYYYMMDD_HHMMSS±HHMM>-<event>-<session>.html containing every section without truncation. The path resolves via git worktree list so linked worktrees still write to the main checkout's reports/ folder. The inline output ends with a Full report: <path> footer line so you can open the complete record in a browser. Add both reports/ and reports_dev/ to your project's .gitignore per the agent-reports-location rule — reports often contain private data (session IDs, file paths, tool outputs) that must never be committed.
• Cost estimate — based on published Anthropic API pricing, scoped to lifetime (agents) or current operation (session)
• Agent identity — agent type/name (via v2.1.101 agent_id/agent_type hook input fields), model, message count, duration
• Bash commands — every shell command executed (full list in HTML, capped inline)
• Web fetches — every URL fetched (full list in HTML, capped inline)
• Files touched — read, edited, and written files (full list in HTML, capped inline)