Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Token usage visibility is the #1 most-requested feature category in Claude Code issues. At least 10+ open issues request overlapping subsets of the same core need:

• Per-session and consolidated token usage visibility in Claude Code #31564 — Per-session and consolidated token usage
• Feature Request: Add command to view all-time cumulative token usage #13891 — All-time cumulative token usage command
• Feature Request: Usage history tracking for Pro/Max subscription users #13892 — Usage history tracking for Pro/Max subscribers
• [FEATURE] Real-time Token Usage Indicator in CLI #10593 — Real-time token usage indicator in CLI
• [FEATURE] Automatic Cost Tracking and Reporting #18550 — Automatic cost tracking and reporting
• Usage Metrics Visibility for Max Subscribers #1109 — Usage metrics visibility for Max subscribers
• [FEATURE] Expose token usage and cost data in hook inputs #11008 — Token usage in hook inputs
• [FEATURE] Add token usage details to status line API #8861 / [FEATURE] Include Token Usage in Status Line JSON #10436 / Expose token usage data to statusline scripts #11535 — Token usage in statusline
• Feature Request: Show remaining plan tokens instead of session context usage #15931 — Remaining plan tokens instead of context usage
• [FEATURE] Agent Token Usage API - Critical Infrastructure for Agent Development Ecosystem #10388 — Agent Token Usage API

The data already exists — every Claude Code session writes detailed JSONL transcripts under ~/.claude/projects/ with per-message usage objects containing input_tokens, output_tokens, cache_creation_input_tokens, and cache_read_input_tokens. But there is no built-in way to query or aggregate this data.

Proposed Solution

A built-in claude usage subcommand (or claude-usage standalone) that provides unified token usage analytics. I've built a working prototype that demonstrates feasibility by parsing the existing JSONL transcripts — no API changes or new data collection required.

1. Summary view (default)

$ claude usage
============================================================
  Claude Code Usage (last 7 days)
============================================================
  Sessions:       19
  Duration:       3080 min (51.3 hrs)
  Messages:       1356
────────────────────────────────────────────────────────────
  Input tokens:         9.6K
  Cache write:          3.5M
  Cache read:         151.0M
  Output tokens:      392.2K
  Total tokens:       155.3M
────────────────────────────────────────────────────────────
  Est. cost:      $282.52
============================================================

2. Plan status + today/weekly overview

$ claude usage --plan
============================================================
  Claude Code Plan Status
============================================================
  Plan:           Max
  Rate Limit:     Max 20x
  Extra Usage:    Disabled
  Active Now:     4 session(s)
============================================================

                        Today           This Week
  ────────────────────────────────────────────────
  Sessions                  6                  19
  Messages                736                1356
  Tokens                91.4M              157.1M
  Est. cost         $186.01            $286.02

3. Live monitoring dashboard

$ claude usage --watch 5
============================================================
  Claude Code Live Monitor
  Updated: 21:27:11   Refresh: 5s   Ctrl+C to quit
============================================================
  Active sessions:  4
  User messages:    701
  Model:            claude-opus-4-6
────────────────────────────────────────────────────────────
  Input tokens:           6.2K
  Cache write:            1.8M
  Cache read:            88.4M
  Output tokens:        231.7K
  Total:                 90.4M
  Delta:                 25.3K  (+25,312)
────────────────────────────────────────────────────────────
  Est. cost:        $184.32
============================================================

                        Today           This Week
  ────────────────────────────────────────────────
  Sessions                  6                  19
  Tokens                91.4M              157.1M
  Est. cost         $186.01            $286.02

  Session    Project           Min  Msgs       In      Out     Cost
  ──────────────────────────────────────────────────────────────────
  20cd51f1   cli-tools         547   698    90.1M   231.5K $183.23
  27e3a24c   cli-tools           0     1    59.7K       64  $0.08

4. Flexible filtering

$ claude usage -d 1                    # Today only
$ claude usage -d 30 --daily           # Daily breakdown for last month
$ claude usage -p my-project           # Filter by project
$ claude usage --sessions -v           # Per-session with summaries
$ claude usage --watch 10 -p project   # Live monitor, filtered

Why this should be built-in (not a third-party tool)

1. The data is already there. Every JSONL transcript contains complete usage objects. No new collection needed.
2. 10+ issues requesting fragments of this. A single unified command resolves all of them.
3. Cache-aware cost estimation matters. Claude Code heavily uses prompt caching — cost estimates that ignore cache_creation_input_tokens and cache_read_input_tokens are wildly inaccurate. A first-party tool can get this right.
4. Plan metadata is already local. ~/.claude/.credentials.json has subscription type and rate limit tier. ~/.claude.json has extra usage status. Combining these into a single view is trivial but only Anthropic can do it correctly.
5. Live monitoring enables cost-conscious usage. Users currently have zero feedback about consumption velocity during long sessions. The --watch mode shows token delta per refresh cycle, letting users see exactly how much each interaction costs.

Implementation notes from the working prototype

Data source: Parse ~/.claude/projects/*/*.jsonl (top-level only, skip subagents/). Each line with message.usage contains the token counts. Session metadata (project, model, timestamps) comes from the same files.

Cost model: Input, output, cache_write (1.25x input price), cache_read (0.1x input price), per-model pricing lookup.

Active session detection: Files modified within last 30 minutes.

Performance: Parsing 20+ transcript files (some 100MB+) takes ~2-3 seconds on first load. For --watch mode, this is acceptable at 5-10s intervals. Could be optimized with seek-to-end for incremental parsing.

What's NOT possible from local data (and that's OK):

• Plan usage percentage (rate limit utilization) — only available via API response headers (anthropic-ratelimit-unified-*-utilization), not cached locally
• Billing-accurate costs — the prototype provides estimates, not invoices

Alternative Solutions

• /cost command — Exists but only shows current session. No history, no aggregation, no cross-session view.
• Console/Admin Dashboard — Requires browser, separate login, admin permissions. Not accessible during active coding.
• OpenTelemetry — Heavy setup, meant for organizational monitoring, not personal usage tracking.
• Statusline hacks — Several issues request exposing tokens to statusline scripts. That's a workaround for not having a proper usage command.

Priority

High — This consolidates the most-requested feature category across 10+ open issues.

Feature Category

CLI commands and flags

Use Case Example

Solo developer on Max plan:
"I want to know if I'm burning through my daily allocation too fast. claude usage --watch shows me real-time consumption velocity, and claude usage --plan gives me today vs. this week at a glance."

Team lead:
"I need to understand which projects consume the most tokens so I can allocate budget. claude usage -d 30 --daily -p frontend gives me a monthly breakdown for a specific project."

Cost-conscious user:
"Before I start a large refactoring session, I check claude usage -d 1 to see what I've already used today. After the session, I compare to understand the cost of that specific task."

Additional Context

Working prototype: ~700 lines of Python, zero dependencies beyond stdlib. Parses existing JSONL transcripts that Claude Code already writes. This is not a "build it from scratch" proposal — it's "expose data you already have."

Related issues this would resolve or subsume:
#31564 #13891 #13892 #10593 #18550 #1109 #15931