claude-tokens

Token usage and cost analyzer for Claude Code and (optionally) OpenClaw session logs.

claude-tokens reads the JSONL session files written under ~/.claude/projects/ (and ~/.openclaw/agents/ when present), and produces a per-day / per-model / per-project breakdown of input, output, cache-write, and cache-read tokens — with an optional USD cost estimate based on Anthropic's public list pricing.

$ claude-tokens --days 7
# AI CLI token usage  2026-04-23 ~ 2026-04-30  (Asia/Shanghai)  group by: day  sources: claude-code
day         msgs   input  output  cache_w  cache_r   total      ≈cost
---------------------------------------------------------------------
2026-04-23  1753  250.6K    1.0M    45.8M   277.8M  324.9M  $1355.56
2026-04-24   601   51.0K  439.0K     9.5M   279.7M  289.7M    $631.24
...
TOTAL       6317    2.5M    4.2M    99.8M    1.45B   1.56B  $4367.07

Works on macOS, Linux, and Windows (any platform Claude Code itself runs on). No third-party dependencies — pure Python standard library, requires Python 3.11+.

Install

With uv (recommended):

uv tool install claude-tokens

With pipx:

pipx install claude-tokens

With plain pip:

pip install --user claude-tokens

Usage

claude-tokens                              # last 7 days, grouped by day
claude-tokens --days 30                    # last 30 days
claude-tokens --from 2026-04-01            # since a specific day
claude-tokens --from 2026-04-01 --to 2026-04-15

claude-tokens --group model                # break down by model
claude-tokens --group project              # by working directory
claude-tokens --group day,model            # nested: day then model

claude-tokens --json                       # JSON output (pipe to jq, etc.)
claude-tokens --watch 5                    # live refresh every 5 seconds

claude-tokens --tz UTC                     # change timezone (default Asia/Shanghai)
claude-tokens --tz +0                      # numeric offsets work too

OpenClaw support

If you also use OpenClaw, claude-tokens automatically picks up its session logs at ~/.openclaw/agents/ (skipping the claude-code and codex shell agents, which would double-count against the native CLIs). The table header lists which sources are active; a new source group key lets you split them apart:

claude-tokens --group source,day

To opt out, point the env var at a non-existent path:

CLAUDE_TOKENS_OPENCLAW_DIR=/dev/null claude-tokens

Note: OpenClaw only records non-zero token usage when its model provider is configured with "api": "anthropic" (or "anthropic-messages"). If you're going through an OpenAI-Completions adapter and seeing zeros, that's a known OpenClaw issue — switch the provider's api field, restart the gateway, and new sessions will have real numbers.

How it works

Claude Code writes one JSONL file per session under ~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl. Each assistant turn contains the server-reported token usage:

{
  "message": {
    "id": "msg_…",
    "model": "claude-opus-4-7",
    "usage": {
      "input_tokens": 6,
      "output_tokens": 724,
      "cache_creation_input_tokens": 51914,
      "cache_read_input_tokens": 0
    }
  }
}

claude-tokens:

1. Walks every *.jsonl under the log directory.
2. Deduplicates by Anthropic's globally unique message.id — the same response may appear in several files due to session resume / rewind / sub-agents, but each API call is counted exactly once.
3. Buckets entries by the local date of their timestamp (configurable timezone) and by the requested --group keys.
4. Multiplies token counts by the configured USD price per million tokens.

Because cache hit/miss is decided server-side and reported back in the same usage object, the cache-read / cache-write columns reflect the actual billed behavior — not a client-side guess.

Pricing configuration

Default pricing covers Anthropic's public list price for the Opus, Sonnet, and Haiku families. To override these rates or add prices for other models (e.g. when routing through Vertex with a negotiated rate, or using third-party models like Qwen / GLM / Kimi), drop a TOML file at the OS-appropriate config path:

# Match by case-insensitive substring against the model id. First match wins,
# so put more specific entries first. User entries always win over defaults.

[[models]]
match = "claude-opus-4-7"
input = 15.0
output = 75.0
cache_create = 18.75
cache_read = 1.5

[[models]]
match = "qwen3"
input = 1.0
output = 4.0
cache_create = 1.0
cache_read = 0.1

Use --pricing-file PATH or CLAUDE_TOKENS_PRICING=PATH to point at a different file.

Environment variables

Caveats

• This reports what your client logged. If you also use Claude Code on another machine or container, those sessions aren't included unless you point --log-dir at a shared location.
• USD cost is an estimate based on list price. Vertex / Bedrock / enterprise contracts may price differently — check your cloud provider's billing report for authoritative numbers.
• Models without a configured price are still counted in the token columns but contribute - (or * in totals) in the cost column.

Comparison with other tools

If you also have ccusage installed, its numbers will differ from claude-tokens's on the same logs. Two reasons, both intentional:

1. Deduplication. Claude Code writes the same assistant message into multiple JSONL files when sessions are resumed, sub-agents capture parent context, or /rewind is used. claude-tokens deduplicates by Anthropic's globally unique message.id — each API call is counted exactly once, matching how Anthropic actually bills. ccusage counts every occurrence, so its token totals are typically 30-70% higher than the real billed amount.
2. Pricing source. claude-tokens ships Anthropic's published list price for the Opus / Sonnet / Haiku families (and lets you override via pricing.toml). ccusage fetches the LiteLLM price table at runtime, which often has different (sometimes much lower) rates for newer model IDs.

If you want to reconcile with your cloud provider's billing report, prefer claude-tokens's dedup'd numbers and substitute your contract pricing in pricing.toml.

License

MIT — see LICENSE.