How to track Claude Code token usage and cost

Five ways to get a number

Pick by what you actually need. Most people want the third row and reach for the first two by accident.

Where the data lives

Both major CLIs keep a full local transcript. This is not telemetry sent somewhere, it is a file on your machine.

# Claude Code: one directory per project, JSONL per session
ls ~/.claude/projects/
# -Users-you-code-myapp/  -Users-you-code-otherapp/

# Codex: flat directory of rollout files
ls ~/.codex/sessions/

# How much history have you accumulated?
du -sh ~/.claude/projects ~/.codex/sessions

# A second Claude account lives wherever CLAUDE_CONFIG_DIR pointed
ls "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects"

One more trap worth knowing before you write anything: if you run a second Claude account under its own CLAUDE_CONFIG_DIR, its history is not under ~/.claude. Any tool that hardcodes the default path silently under-reports your real spend by whatever the second account did.

Reading the token counts

Every assistant message in the JSONL carries a usage object. The four counts bill at different multipliers, so summing them into one number gives you a wrong answer, usually by an order of magnitude.

{
  "type": "assistant",
  "message": {
    "id": "msg_01ABC...",
    "model": "claude-sonnet-5",
    "usage": {
      "input_tokens": 1204,
      "output_tokens": 892,
      "cache_creation_input_tokens": 18340,
      "cache_read_input_tokens": 96210
    }
  },
  "requestId": "req_01XYZ..."
}

The JSONL does not tell you which cache duration was used, so a parser has to pick a convention. Most tools assume the 5-minute write at 1.25x, which is right for interactive sessions on the default. If you set 1-hour caching deliberately, your real cost is higher than any generic tool will report.

A working calculation

Here is a minimal version that gets the shape right. It is not production quality, but it produces a defensible number in a few seconds.

cat ~/.claude/projects/*/*.jsonl \
  | jq -s '
      map(select(.type == "assistant" and .message.usage))
      | unique_by(.message.id + ":" + (.requestId // ""))
      | map({
          model: .message.model,
          i:  .message.usage.input_tokens,
          o:  .message.usage.output_tokens,
          cw: (.message.usage.cache_creation_input_tokens // 0),
          cr: (.message.usage.cache_read_input_tokens // 0)
        })
      | group_by(.model)
      | map({
          model:  .[0].model,
          input:  (map(.i)  | add),
          output: (map(.o)  | add),
          cacheW: (map(.cw) | add),
          cacheR: (map(.cr) | add)
        })
    '

cost = (input  * in_rate
      + output * out_rate
      + cacheW * in_rate * 1.25
      + cacheR * in_rate * 0.10) / 1e6

The deduplication trap

Retried and streamed turns can appear more than once in the transcript. Deduplicate on message ID plus request ID before summing, or your totals drift upward over time in a way that is very hard to notice, because nothing ever looks obviously wrong.

cat ~/.claude/projects/*/*.jsonl \
  | jq -s 'map(select(.message.usage))
           | { raw: length,
               deduped: (unique_by(.message.id + ":" + (.requestId // "")) | length) }'

Using ccusage

You do not have to write this yourself. ccusage by ryoppippi is the established open-source tool for exactly this. It handles the path encoding, the dedup, and the pricing table, and it now reports across a long list of agent CLIs, not only Claude.

npx ccusage@latest daily      # spend per day
npx ccusage@latest weekly     # roll up by week
npx ccusage@latest monthly    # roll up by month
npx ccusage@latest session    # per session
npx ccusage@latest blocks     # by 5-hour billing window

# Per-source reports: codex, opencode, gemini, copilot and more
npx ccusage@latest codex daily

When you need per-user numbers instead

Local parsing answers "what did this machine do". For a team you need attribution, and there are three official routes depending on how you buy Claude Code.

OpenTelemetry is the only option that works on every setup and streams per-user token and cost metrics into your own stack in near real time.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_METRIC_EXPORT_INTERVAL=60000   # ms, this is the default

The metrics it emits are claude_code.session.count, claude_code.token.usage, claude_code.cost.usage, claude_code.lines_of_code.count, claude_code.commit.count, claude_code.pull_request.count, claude_code.code_edit_tool.decision, and claude_code.active_time.total. Cost is in USD; tokens are counted per type.

What the number means on a subscription

If you are on Pro, Max, or a Team seat, you are not billed per token, so a dollar figure derived from API rates is not an invoice. It is still the most useful number you can compute, for three reasons.

1. It tells you whether your plan is good value. If a $100 Max 5x plan does $600 of notional API work a month, that is a clear answer. Anthropic's own published average is around $13 per developer per active day on metered billing, so a full-time month lands around $150 to $250.
2. It attributes consumption. "This one repo is 70% of my usage" is actionable in a way that "I hit my limit again" is not.
3. It prices habits. Seeing that running full test suites through the agent costs more than the rest of the session combined changes the habit within a day.

Common mistakes

Questions people ask

Keep reading