token-audit

name	token-audit
description	Use when the user asks where their Claude Code usage/tokens are going, is burning through their plan unexpectedly fast, hitting limits, or wants a breakdown of Claude Code activity. Produces a COMPREHENSIVE usage report from local session transcripts: tokens by day/model/project, tool usage, MCP usage, subagent fan-out, web-tool calls, cache efficiency, busiest sessions, hourly activity, and a runaway-daemon cross-reference — distinguishing interactive work from automation and recommending concrete fixes.
user-invocable	true

Claude Code Usage Audit (token-audit)

A comprehensive picture of Claude Code usage in this container, built from the local session transcripts in ~/.claude/projects/**/*.jsonl (each assistant message records its token usage, tool calls, model, and metadata). This covers ALL Claude Code activity — interactive, subagents, hooks, MCP, web tools — and answers two questions: where is my usage going? and is any of it runaway automation?

Engine adapted (MIT) from pacphi/agentic-kit's ruflo-token-audit; see the attribution header in the script. Stdlib-only Python, no network, no extra dependencies.

When to use

Trigger on: "where are my tokens/usage going", "why is my usage so high", "break down my Claude Code activity", "I'm hitting my Max/Pro limit", "what am I spending tokens on", "audit token usage". Also proactively if the user mentions surprising usage.

Procedure

1. Run the engine (baked at the skills tree; stdlib-only Python 3):

   python3 /opt/agentbox/skills/token-audit/scripts/token-audit.py --days 7
   

   • Honour any window the user gives ("past month" → --days 30).
   • --top N widens each section; --json gives machine-readable output; --no-daemons skips the ps cross-reference.

2. Read the whole picture, then lead with the headline. Synthesize, don't echo. Key sections and what they tell you:

   Section	Read it for
   BY MODEL	Opus/Fable = interactive; heavy Haiku/Sonnet = automation/subagents
   SESSIONS PER DAY	tens = human; hundreds–thousands = automation (≈one/min = robotic)
   ACTIVITY BY HOUR	a flat 24h histogram (busy at 3am) is automation, not a person
   TOOL USAGE	what the work actually is (Bash/Read/Edit vs Task/MCP)
   MCP USAGE	per-server call volume; heavy MCP also means a per-session tool-def tax
   SUBAGENT FAN-OUT	Task spawns + sidechain share — how much is delegated/parallel
   BUSIEST SESSIONS	a single runaway conversation surfaces here by token total
   CACHE EFFICIENCY	high cache-read% is normal/cheap; flag only with huge automated volume
   STARTUP CONTEXT TAX	fixed per-session cost (CLAUDE.md + tool/skill manifests) × many sessions
   RUNNING DAEMONS	live ruflo daemon start processes mapped to top-burn projects

3. Check the daemon cross-reference (the classic leak upstream: six leaked daemons produced ~8.1B tokens in a week, ~94% background). In agentbox, ruflo AI workers are pinned off (RUFLO_DAEMON_AI_WORKERS=0 in the runtime env) and no ruflo daemon runs under supervisord — so ANY daemon in this section is unexpected. If daemons are listed and the user authorises:

   python3 /opt/agentbox/scripts/ruflo-daemon-gc.py           # preview
   python3 /opt/agentbox/scripts/ruflo-daemon-gc.py --kill    # stop them
   

   Then re-run the audit to confirm.

4. Report like a diagnosis, not a data dump. Lead with the verdict (where usage is going + interactive vs automation + the single biggest driver). Then a small supporting table, then ranked concrete fixes with exact commands. Levers worth naming: kill runaway daemons; trim an oversized CLAUDE.md; drop or gate a heavy always-on MCP (its tool defs are a per-session tax); reduce hook/loop fan-out.

Caveats (be honest)

• The cost-weight is an Opus-equivalent reference to compare line items — NOT the user's actual plan billing. Don't present it as dollars owed.
• High cache-read is normal and cheap; flag it only when it's huge and multiplied by thousands of automated sessions.
• A few hundred sessions (or Task spawns) from legitimate parallel subagent work is not a leak. The tell is unattended, repeating activity — flat overnight hours, near-identical session counts across projects, daemons running.
• Consultant-tier calls (codex/zai/perplexity/deepseek MCP servers) are logged separately under /var/lib/agentbox/consultations/*.jsonl — this audit sees their MCP call counts, not their provider-side token spend.

Sample prompts

• "Audit my Claude Code usage for the last 7 days — where is it all going?"
• "Break down what I've been spending tokens on this week."
• "I'm hitting my Max limit in a day. Run the usage audit and tell me why."
• "Check for runaway ruflo daemons and show me my heaviest sessions."