map-tokenreport · diff
git:20260618.1acadce to git:20260626.911e730
129 added, 17 removed. Audit A to A.
---
name: map-tokenreport
description: |
- Show per-subtask/agent token accounting (input, output, cache read/creation, cost, cache-hit ratio) for the current branch. Use when asked for token usage, run cost, or a token report. Do NOT use to plan or run work; use map-efficient.
+ 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]"
+ 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
```bash
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):**
```bash
python3 .map/scripts/map_step_runner.py token_report "$BRANCH"
```
- `token_report` re-reads `token_log.jsonl`, rebuilds `token_accounting.json`,
- and prints a per-subtask table, a per-agent table, research ROI, and a TOTAL
- line with the cache-hit ratio and estimated cost. It is idempotent and read-only
- against your code.
+ **Dashboard (visual):**
+ ```bash
+ python3 .map/scripts/map_step_runner.py token_report "$BRANCH" --dashboard
+ ```
+ **History (trends):**
+ ```bash
+ python3 .map/scripts/map_step_runner.py token_report "$BRANCH" --history
+ ```
+
+ **Estimate:**
+ ```bash
+ python3 .map/scripts/map_step_runner.py token_report "$BRANCH" --estimate
+ ```
+
+ **JSON / CSV export:**
+ ```bash
+ 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:**
+ ```bash
+ 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:
```bash
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):
```text
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:
```text
/map-tokenreport
```
- Report for a specific branch:
+ Visual dashboard:
```text
- /map-tokenreport feat/add-multiply
+ /map-tokenreport --dashboard
```
- Typical output:
+ Trend over last 5 sessions:
```text
- Token accounting — feat-add-multiply (93 assistant turns)
+ /map-tokenreport --history 5
+ ```
- subtask input output cache_rd cache_cr $cost
- -------------------------------------------------------------------------
- ST-001 183 150,879 14,085,841 792,780 47.31
- -------------------------------------------------------------------------
- TOTAL 183 150,879 14,085,841 792,780 47.31
+ Cost estimate before starting:
- cache hit ratio: 100.0% est cost: $47.31
+ ```text
+ /map-tokenreport --estimate
```
+ Export for CI pipeline:
+
+ ```text
+ /map-tokenreport --json > .map/token_report.json
+ ```
+
+ Record a snapshot (typically called automatically by the Stop hook):
+
+ ```text
+ /map-tokenreport --finalize
+ ```
+
+ Typical dashboard output:
+
+ ```text
+ ┌─────────────────────────────────────────────────────────────────┐
+ │ 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:
+
+ ```text
+ 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:
+
+ ```text
+ 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.