stevengonsalvez/token-usage
toolkit/packages/skills/token-usage/SKILL.md
Show Claude Code token usage across sessions — daily, weekly, per-project, and per-session breakdowns. Parses {{HOME_TOOL_DIR}}/projects/**/*.jsonl for consumption data. Use when the user asks about token usage, costs, how many tokens were used, session statistics, or wants a usage report.
$ install --global
skillsauthnpx skillsauth add stevengonsalvez/agents-in-a-box token-usageInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 7, 2026, 4:55 AM141.1s2 files scanned
SKILL.md
- name:
- token-usage
- description:
- Show Claude Code token usage across sessions — daily, weekly, per-project, and per-session breakdowns. Parses {{HOME_TOOL_DIR}}/projects/**/*.jsonl for consumption data. Use when the user asks about token usage, costs, how many tokens were used, session statistics, or wants a usage report.
- user-invocable:
- true
- argument-hint:
- [--days N] [--since YYYY-MM-DD] [--project NAME]
Token Usage
Analyze Claude Code token consumption across all sessions.
How to Run
IMPORTANT: Always use --format markdown and display the full output directly to the user as markdown tables. Do NOT summarize or truncate.
Run the script and display the FULL output as-is:
python3 {{HOME_TOOL_DIR}}/skills/token-usage/scripts/token_usage.py --format markdown [ARGS]
Pass through any user-provided arguments (--days, --since, --project, --top-sessions).
Examples
# All time usage
python3 {{HOME_TOOL_DIR}}/skills/token-usage/scripts/token_usage.py --format markdown
# Last 7 days
python3 {{HOME_TOOL_DIR}}/skills/token-usage/scripts/token_usage.py --days 7 --format markdown
# Since a specific date
python3 {{HOME_TOOL_DIR}}/skills/token-usage/scripts/token_usage.py --since 2026-04-01 --format markdown
# Filter to a specific project
python3 {{HOME_TOOL_DIR}}/skills/token-usage/scripts/token_usage.py --project shotclubhouse --format markdown
# Top 20 costliest sessions
python3 {{HOME_TOOL_DIR}}/skills/token-usage/scripts/token_usage.py --days 30 --top-sessions 20 --format markdown
# JSON output (for piping to jq)
python3 {{HOME_TOOL_DIR}}/skills/token-usage/scripts/token_usage.py --format json | jq '.grand_total'
Display Instructions
After running the script:
- Show the ENTIRE markdown output directly in your response — do not hide it behind a Bash tool call
- The output is already formatted as markdown tables — just paste it verbatim
- Do NOT add your own summary or interpretation unless the user asks for one
- If the output is long, show all of it — the user wants to see the full report
CLI Flags
| Flag | Description | Default |
|------|-------------|---------|
| --days N | Only include last N days | All time |
| --since YYYY-MM-DD | Only include since this date | All time |
| --project NAME | Filter to project (substring match) | All projects |
| --top-sessions N | Number of top sessions to show | 10 |
| --format text\|markdown\|json | Output format | text |
| --projects-dir PATH | Override projects directory | {{HOME_TOOL_DIR}}/projects |
Data Source
Parses {{HOME_TOOL_DIR}}/projects/**/*.jsonl — Claude Code's session transcript files. Each assistant message contains a usage block with input_tokens, cache_creation_input_tokens, cache_read_input_tokens, and output_tokens.
Integration with ainb-tui
The ainb-tui has a built-in Usage Analytics screen (press i from home screen or select "Stats" in the sidebar) that provides the same data with a visual bar chart and provider selector. This skill is the CLI-only alternative.
Notes
- Token counts are RAW — they don't map directly to cost since cache reads are heavily discounted and different models have different pricing
- The script is pure Python 3 with no external dependencies (uses only stdlib)
- For cost estimates, multiply by model-specific per-token pricing from Anthropic's pricing page
Related Skills
stevengonsalvez/reflect:cost
documentation
VerifiedTrustedCommunity
Report reflect drain spend over a time window — tokens split by cached (cache_read), uncached writes (cache_creation), and io (input+output), with a $ estimate, grouped by day / outcome / model / transcript. Reads the drainer's cost log and surfaces outlier runs and cache-reuse health (the 41.5M-token failure mode = low cache reuse + high cache writes). Use to answer "what is reflection costing me" for the last day / week.
12SKILL.mdUpdated Jun 2, 2026
stevengonsalvez/ainb-fleet:standup
development
VerifiedTrustedCommunity
Show fleet status — every claude session running on the host, merged across ainb + claude-peers broker + background jobs. Use when you need to enumerate sessions before composing an action, see which sessions have a peer registered (broker-routable) vs tmux-only, check the `summary` of each session, or pipe the list into jq for filtering. Default output: text table. Pass --format json for LLM consumption.
10SKILL.mdUpdated May 31, 2026
stevengonsalvez/ainb-fleet:sequence
testing
VerifiedTrustedCommunity
Ordered multi-step prompts to fleet targets, ack-gated between steps via JSONL assistant-turn-end detection. Use for cycles like disconnect→reconnect→verify, or any flow where step N+1 requires step N to have completed first. The skill BLOCKS until each target's transcript shows the next assistant turn finishing OR per-step timeout fires (default 300s).
10SKILL.mdUpdated May 31, 2026
stevengonsalvez/ainb-fleet:needs
development
VerifiedTrustedCommunity
Center control panel — enumerate every claude session that is blocked waiting on something: a user answer (AskUserQuestion fired), an API error retry, an idle assistant turn-end with no follow-up, or an explicit WAITING: marker. Returns rich JSON with signal kind + context per session. Use this when you've stepped away from the fleet and want one place to see everything that wants your attention and answer it.
10SKILL.mdUpdated May 31, 2026