| name | map-tokenreport |
| description | Show per-subtask/agent token accounting (input, output, cache read/creation, cost, cache-hit ratio) for the current branch. Supports --dashboard (box-drawing visual), --history (trends), --estimate (cost projection), --json / --csv export, and --finalize (record session snapshot). Use when asked for token usage, run cost, or a token report. Do NOT use to plan or run work; use map-efficient.
|
| effort | low |
| disable-model-invocation | true |
| argument-hint | [branch] [--dashboard|--history|--estimate|--json|--csv|--finalize] |
/map-tokenreport - Token Accounting Report
Purpose: surface how many tokens (and how much money) the current branch's MAP
run spent, attributed to the subtask, phase, and agent that spent them.
Read-only reporting — this skill does not plan, implement, or run quality
gates.
Constraints (NEVER)
This skill is strictly read-only reporting.
- NEVER edit code, state, or git from this skill — it renders an existing rollup and stops.
- NEVER run or resume a MAP workflow here; if work is needed, hand off to
/map-efficient.
- NEVER present
est_cost_usd as a billing source of truth — it is a per-model estimate.
The numbers come from the map-token-meter hook (wired on SubagentStop and
Stop), which reads each Claude Code transcript's per-turn usage block and
appends attributed rows to .map/<branch>/token_log.jsonl, rolled up into
.map/<branch>/token_accounting.json. This skill just renders that rollup.
What it shows
- input / output tokens, cache_read (cheap cache hits) and
cache_creation (cache writes) — tracked separately because they bill at
very different rates.
- est_cost_usd — priced per model via
MODEL_TOKEN_PRICES in
map_step_runner.py (estimate, not a billing source of truth).
- cache_hit_ratio =
cache_read / (input + cache_read) — how well prompt
caching is paying off.
- Breakdowns by subtask, by agent (actor / monitor / research-agent /
orchestrator / ...), and by phase.
- research_roi — research-agent / Codex researcher tokens and cost compared
with downstream Actor/Monitor tokens, so users can see whether delegated
exploration paid for itself.
Modes
The skill supports several modes via CLI flags:
| Flag | Effect |
|---|
| (default) | Classic text table: per-subtask rows, by-agent section, research ROI, cache-hit + cost |
--dashboard | Box-drawing visual dashboard: subtask bar chart, per-agent + per-model breakdowns, vs-previous comparison |
--history [N] | Trend table over last N recorded sessions (default 10) with cost delta and cache-hit trend |
--estimate | Cost projection from weighted historical average, with range, median, and remaining estimate |
--json | Export token_accounting.json as formatted JSON |
--csv | Export as CSV (one row per dimension key: aggregate, subtask, agent, phase) |
--finalize | Record current token_accounting.json as a snapshot in token_history.jsonl for trend tracking |
Steps
Step 1: Resolve the branch
BRANCH=$(git rev-parse --abbrev-ref HEAD | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||')
If the user passed an explicit branch argument, use it instead of the detected
one.
Step 2: Render the report
Choose the right command for the user's intent:
Default (classic table):
python3 .map/scripts/map_step_runner.py token_report "$BRANCH"
Dashboard (visual):
python3 .map/scripts/map_step_runner.py token_report "$BRANCH" --dashboard
History (trends):
python3 .map/scripts/map_step_runner.py token_report "$BRANCH" --history
Estimate:
python3 .map/scripts/map_step_runner.py token_report "$BRANCH" --estimate
JSON / CSV export:
python3 .map/scripts/map_step_runner.py token_report "$BRANCH" --json
python3 .map/scripts/map_step_runner.py token_report "$BRANCH" --csv
Record snapshot for history:
python3 .map/scripts/map_step_runner.py token_report "$BRANCH" --finalize
Step 3: Optional — inspect the raw rollup
For the per-phase split or per-subtask research ROI details, read the JSON
directly:
jq '{aggregate, by_agent, by_phase, research_roi}' ".map/${BRANCH}/token_accounting.json"
Step 4: Summarize
Emit exactly this report shape, then STOP (this skill never changes code):
Tokens (<branch>): in <I> / out <O> / cache_rd <CR> / cache_cr <CC>
Cache-hit ratio: <X>% · Est. cost: $<C> · Research share: <R>%
Most expensive: <subtask|agent> ($<amount>)
Flags: <low cache-hit | high research cost | none>
Fill every field from the token_report output. If a value is unavailable, write n/a — never omit a line or invent a number.
Examples
Report token usage for the current branch:
/map-tokenreport
Visual dashboard:
/map-tokenreport --dashboard
Trend over last 5 sessions:
/map-tokenreport --history 5
Cost estimate before starting:
/map-tokenreport --estimate
Export for CI pipeline:
/map-tokenreport --json > .map/token_report.json
Record a snapshot (typically called automatically by the Stop hook):
/map-tokenreport --finalize
Typical dashboard output:
┌─────────────────────────────────────────────────────────────────┐
│ MAP Token Report — feat-oauth2 │
│ │
├─────────────────────────────────────────────────────────────────┤
│ Session: $ 3.42 Cache-hit: 67% │ vs prev: ↑12% │
│ Turns: 93 │ │
├─────────────────────────────────────────────────────────────────┤
│ Per-subtask │
│ │
│ ST-001 $ 0.87 █████████████████████████████░░░░ 28% │
│ ST-002 $ 1.23 ██████████████████████████████████████ │
│ ST-003 $ 0.65 █████████████████████░░░░░░░░░░░░ 21% │
│ ST-004 $ 0.67 ██████████████████████░░░░░░░░░░░ 22% │
├─────────────────────────────────────────────────────────────────┤
│ By agent │
│ actor $ 1.89 (55%) │
│ monitor $ 0.67 (20%) │
│ evaluator $ 0.44 (13%) │
│ predictor $ 0.42 (12%) │
├─────────────────────────────────────────────────────────────────┤
│ By model │
│ claude-sonnet-4-6 $ 2.10 (61%) │
│ claude-haiku-4-5 $ 1.32 (39%) │
└─────────────────────────────────────────────────────────────────┘
Typical history output:
Token history — feat-oauth2 (last 3 of 3 sessions)
# timestamp turns cost cache% vs prev
-------------------------------------------------------------------
1 2026-06-24T10:15:00 45 $ 2.87 58% —
2 2026-06-25T14:22:00 72 $ 3.15 62% +10%
3 2026-06-26T09:30:00 93 $ 3.42 67% +9%
Trend (3 sessions):
Cost: $ 2.87 → $ 3.42 ↑ 19%
Cache: 58% → 67% ↑ 9pp
Avg cost: $ 3.15 / session
Typical estimate output:
Cost estimate — feat-oauth2
Based on 3 historical sessions (last 3 weighted):
Weighted avg: $ 3.22
Range: $ 2.87 — $ 3.42
Median: $ 3.15
Spent so far: $ 1.20
Remaining est: $ 2.02
Troubleshooting
token_accounting.json does not exist / report is empty. The
map-token-meter hook has not fired for this branch yet. It records on
SubagentStop and Stop, so a brand-new branch with no completed turns has
nothing to show. Confirm the hook is wired in .claude/settings.json
(SubagentStop and Stop entries) and that .map/<branch>/token_log.jsonl
exists.- Everything is attributed to
orchestrator / unattributed. Those turns
ran outside a MAP subtask (e.g. direct edits, or before step_state.json had
a current_subtask_id). Per-subtask attribution appears once a
/map-efficient run sets the active subtask.
- Cost looks high relative to raw input. That is expected when most input
is cached:
cache_creation is the dominant cost on cache-heavy runs. Compare
cache_creation vs cache_read and the cache-hit ratio to see where the
spend goes.
- Unknown model in cost estimate.
MODEL_TOKEN_PRICES falls back to the
default model price for unrecognized model ids; update that table in
map_step_runner.py when a new model ships.
--history / --estimate show no data. No snapshots have been recorded.
Run /map-tokenreport --finalize at the end of each session, or set up the
Stop hook to call record_session_snapshot automatically.- Dashboard layout looks wrong in narrow terminals. The dashboard uses
a fixed 67-character width. Pipe the output to a file and view it in a wider
terminal, or use
--json for programmatic consumption.
