Skip to content

Cost Report

Jump to bottom
Eugene Naumov edited this page May 11, 2026 · 1 revision

Cost Report

agent-notes tracks token usage and cost across all agents in a session, providing per-agent breakdowns and savings calculations.

Usage

agent-notes cost-report                              # current session
agent-notes cost-report --since 2026-05-11T12:00:00Z # filter by time
agent-notes cost-report --session <session-id>       # specific session

Flags

Flag Description
--since <ISO-datetime> Only include messages at or after this UTC datetime (ISO 8601)
--session <id> Report on a specific session (Claude Code only)
-h, --help Show help

How It Works

  1. Session detection: Checks environment variables to determine the active AI CLI:

    • CLAUDECODE or CLAUDE_CODE_ENTRYPOINT — Claude Code backend
    • CLAUDE_CODE_SESSION_ID — used automatically when available
    • OPENCODE or OPENCODE_SESSION_ID — OpenCode backend
    • Neither — picks whichever backend has more recent data

  2. Transcript reading: Reads JSONL transcripts from ~/.claude/projects/<slug>/<session-id>.jsonl

  3. Subagent discovery: Reads subagent transcripts from <session-id>/subagents/agent-*.jsonl

  4. Token aggregation: Groups usage by agent label and model, calculates costs using per-model pricing

  5. Baseline comparison: Calculates what the session would have cost on Claude Opus 4.7 (the most expensive model) to show savings from tiered model usage

Output Format

Session: edc0f807-1307-483f-9c26-b3107f937514
Started: 2026-05-11T14:58:27Z
Last activity: 2026-05-11T21:14:38Z
Elapsed: 6h 16m
Configured: reasoner=claude-opus-4-6, scout=claude-haiku-4-5, worker=claude-sonnet-4-6

agent(model)                    in/out/cache        time     actual     vs Claude Opus 4.7
------------------------------------------------------------------------------------------
lead(claude-opus-4.6)           35k/300k/45m        6h 0m    $30.00     $30.00
coder(claude-sonnet-4.6)        300/40k/10m         8m 0s    $3.50      $5.80
explorer(claude-haiku-4.5)      1k/60k/15m          10m 0s   $1.80      $9.00
TOTAL (saved 23%)               36k/400k/70m        6h 18m   $35.30     $44.80

Columns

Column Description
agent(model) Agent name and model used for that agent's work
in/out/cache Input tokens / output tokens / cache read tokens
time Wall-clock time for this agent's work
actual Actual cost based on the model's pricing
vs Claude Opus 4.7 What it would have cost if everything ran on Opus (baseline)

Savings Calculation

The "saved X%" in the TOTAL row shows cost savings from using tiered models:

  • Scout work (Haiku) at ~$0.25/M vs Opus at $15/M — 60x cheaper
  • Worker work (Sonnet) at ~$3/M vs Opus at $15/M — 5x cheaper
  • Lead/Reasoner (Opus) — no savings, same model as baseline

Typical savings range from 15-30% depending on how much work is delegated to cheaper tiers.

Integration

The cost report is designed to run at the end of every AI response. In a typical setup:

  • The lead's CLAUDE.md instructions include "run agent-notes cost-report at the end of every response"
  • The output is rendered as a markdown table in the conversation
  • Cumulative for the entire session (not per-message)

Troubleshooting

"No Claude Code transcript found for this project": The CLI couldn't find a matching transcript. This can happen if:

  • The session ID doesn't match any JSONL file
  • The working directory slug doesn't match (symlink issues)
  • Fix: The CLI uses CLAUDE_CODE_SESSION_ID env var as fallback and resolves symlinks automatically

"No assistant messages found": The session transcript exists but contains no AI responses yet (very early in a session).

Clone this wiki locally