[FEATURE] Built-in Usage Analytics Command (claude usage) — Consolidates 10+ Open Issues

I ran into the same gap and ended up building an MCP server that reads local session data and exposes cost tools. Works inside Claude Code, Cline, and Cursor directly.

Five tools: session cost, cumulative per-project costs across all sessions ranked by spend, cache savings analysis, monthly cost projection vs Max subscription, and subagent cost attribution.

Auto-detects which AI coding tools are installed and aggregates data from all of them. Also runs as a SessionEnd hook for automatic cost logging on exit:

{
  "hooks": {
    "SessionEnd": [{"hooks": [{"type": "command",
      "command": "npx @f3d1/llmkit-mcp-server --hook"}]}]
  }
}

Free, open source, no API key needed for the local tools.

npm: @f3d1/llmkit-mcp-server
github: https://github.com/smigolsmigol/llmkit

This consolidation is overdue — glad to see the 10+ fragmented issues pulled together.

I've been running my own analysis on session JSONL files for the past few weeks, and the data validates every use case listed in this issue. A few things I found that might be useful for scoping the implementation:

The data is already there, and it's rich. A single session JSONL file from ~/.claude/projects/ contains per-turn token counts broken down by input, output, cache_read, and cache_creation — plus model identifiers and tool call metadata. Parsing this into a useful report is straightforward. In my testing, a 200KB JSONL file (37 turns) processes in ~6ms.

Cache costs dominate. In every session I've analyzed, cache_read and cache_creation together account for 80-95% of the estimated cost. A claude usage command that only shows input/output tokens would miss the majority of the spend. The breakdown needs all four categories.

Model selection is the biggest optimization lever. In one session, 33 out of 37 Opus turns were doing simple operations (single tool call, <500 output tokens) that Sonnet handles identically at 1/5 the cost. Surfacing this in a usage report would immediately tell developers where to add model routing hints.

I built a CLI tool that does exactly what this issue describes — parses JSONL transcripts and produces a cost report:

npx agent-forensics analyze ~/.claude/projects/-Users-me/ --full

It covers: per-model cost breakdown, tool usage frequency, sub-agent detection, waste pattern identification (redundant reads, debug loops, model misuse), and estimated savings. The --json flag outputs machine-readable data for scripting.

You can also see the report format without installing anything:

curl -s https://api.agentsconsultants.com/forensics/sample | jq .

Full disclosure: I built this tool. It's MIT-licensed and the analysis runs entirely locally (no data leaves your machine). Would love to see the core functionality land natively in Claude Code — the 700-line prototype mentioned in this issue is the right approach. Happy to share implementation notes if useful.

Unified claude usage command

Issues addressed: #33978 · #27915 · #7328 Also closes: #20636 · #23512 · #6057 (and 17+ other duplicates)

Hi @mp719lkh — great issue writeup and prototype. I'd like to build on your work and contribute a production-ready implementation that also pulls in the closely related rate-limit (#27915) and MCP context budget (#7328) requests.

Why unify them

All three issues boil down to the same gap: users can't see what Claude Code is consuming. A single observability surface is cleaner than three separate additions — and it closes 23+ duplicate issues in one shot.

What I've built

2,100+ lines of TypeScript, 45 tests passing, zero new dependencies. Full repo: Omsatyaswaroop29/claude-usage-contribution

claude usage                      # Token totals, cost, cache hit rate, model/project breakdowns
claude usage --rate-limit         # Session/daily usage %, requests remaining, reset time
claude usage --mcp-breakdown      # Per-server and per-tool context window cost
claude usage --watch              # Live-updating display
claude usage --json               # Machine-readable output for CI/CD

Interactive demo — click the tabs to see each mode with typing animation and bar charts.

How it works

Like your prototype, the parser reads existing JSONL transcripts at ~/.claude/projects/ — no API changes needed. Key differences from the prototype:

• Streaming architecture — processes line-by-line via readline, never loads full files into memory
• Rate-limit layer — parses anthropic-ratelimit-* headers and extends the statusLine JSON payload
• MCP introspector — estimates per-tool context window cost from tools/list responses
• Zero dependencies — Node.js built-ins only. Token estimation uses ~4 chars/token heuristic

Modules

| Module | What it does |
|---|---|
| UsageParser | Stream JSONL, filter by date/model/project, skip malformed lines |
| UsageAggregator | Incremental metrics: tokens, cost, cache hit rate, per-model/project/day rollups |
| RateLimitCollector | Parse API headers → rate_limits object for statusLine |
| MCPIntrospector | Estimate per-tool token cost → --mcp-breakdown output |
| TerminalFormatter | Bar charts, ANSI color, JSON mode |
| UsageCommand | CLI handler with all flags |

Real-world use case this would solve: context optimization for heavy CLI users.

I maintain large context files (CLAUDE.md, SESSION.md, project docs) that Claude Code loads every session. Right now I have no way to measure whether trimming them actually reduces token consumption — /cost returns "using subscription" for Pro users, and /usage only surfaces the 4h rate limit window. The Desktop App shows token counts during processing, but that data never surfaces in the CLI for subscribers.

What I actually need is simple: input/output tokens per session, or even just context window % used. Not billing data — just enough signal to answer "did that doc trim make a difference?"

The JSONL approach @digitalpromptmarket-beep described and the implementation @Omsatyaswaroop29 shared both seem like they'd cover this. Just adding the use case as validation that the gap is real.

(Comment drafted with guidance from Claude Sonnet 4.6 via Claude Code CLI, which also helped research existing issues before posting.)

Pro subscriber on Linux here. The /usage command previously showed per-session and per-week usage summaries, which was very useful for tracking spend. After upgrading to Claude Code 2.x, it now says usage is only available for subscription plans. Pro plan users lost visibility into their usage with this change — would love to see it restored.

The real-time monitoring side of this already has a path: rate_limits (five_hour.used_percentage, seven_day.used_percentage, resets_at) shipped in statusLine stdin JSON since v2.1.80. I built claude-lens on top of it, showing live usage %, pace delta (burning faster or slower than the reset window), and countdown to reset.

@katsboxofhustles This can restore your quota visibility on Pro today without waiting for a built-in command. It won't cover the historical/aggregate analytics @mp719lkh proposes, but the live piece works now.

The aggregation/summary side of this proposal is solid. One angle I think is missing from
the --watch mode: burn-rate derivatives.

Every tool in this space shows where you are. None show how fast you're getting there.
This matters because conversations have QUADRATIC COSTS because each turn resends the full context.

Three metrics that would make --watch actionable, not just informational:

1. Burn rate

context growth per API call (windowed, reset after compaction).
"Each interaction adds ~12k" is more useful than "you're at 340k."

1. Context tax

(overhead / 1M) × cacheReadRate = the dollar cost per call of
carrying history. Makes the abstract concrete: "$0.38/call just for conversation baggage."

1. /clear savings projection

what clearing and reloading from a handoff would save
over the next N calls. Removes the guesswork from the "keep going or /clear?" decision.

These could surface as a single line in the --watch output:

Burn: +8.2k/call (steady) | Ctx tax: $0.18/call | /clear saves ~$3.40 over 20 calls

Turns the live monitor from a dashboard into a workflow optimizer.

+1 on the core request. Beyond tokens.used/max/remaining, two small additions would
unlock statusline features that currently can't be built reliably:

tokens.delta
tokens added by the last API call (context growth). This is the raw
ingredient for burn-rate display. Without it, statusline tools must re-parse the full JSONL
every refresh to compute a diff — fragile, slow on large files, and breaks after compaction.

tokens.compactions
count of auto-compaction events this session. Any external tool
tracking deltas needs to know when context shrunk. A drop from 180k to 90k isn't
"negative burn" but a compaction. Without this signal, rate calculations produce
nonsense after every compaction event.

Both are single integers the runtime already has in memory. Minimal implementation cost,
but they're the two values that can't be reliably derived externally, unlike used/max which
can at least be approximated from JSONL sums.

I've been working on this in CCM (bash CLI tool for Claude Code management). It has a few usage commands that might help:

• ccm usage sessions - shows per-session token count and estimated cost with model-specific pricing
• ccm usage history --days 30 - per-project and per-day token breakdown
• ccm usage dashboard - per-account usage if you manage multiple accounts
• ccm session summary - shows what happened in each session (topic, tools used, files modified)

All parsed from the existing JSONL session files - no extra dependencies.

https://github.com/dr5hn/ccm

+1

Use case: Pro/Max subscriber, heavy agent/skill usage, optimization-focused

I'm on a Pro/Max plan (no per-token billing), but I'd still find token tracking extremely valuable for optimizing my workflow rather than managing costs.

I use agents extensively — multiple background agents per session, custom skills, and multi-step tool chains. Right now I have no visibility into which agents or skills are consuming the most context, which makes it hard to know where to focus optimization efforts (e.g., trimming prompts, reducing context passed to sub-agents, simplifying skill instructions).

What I'd specifically want:

• Token count per agent invocation (input + output)
• Token count per skill execution
• Session-level totals, broken down by agent vs. main thread

Even a simple claude usage summary at the end of a session — or surfaced in the status line — would give enough signal to guide optimization. This doesn't need to be a billing feature; it's a developer productivity feature for power users who want to reason about context efficiency.

Strong +1. As a 2× Max subscriber running long agentic sessions (10–30 hours), I cannot currently answer a basic operational question: "which skills/workflows/sessions are burning the most tokens, and how much of that is rework vs productive work?"

Microcompact-driven silent re-reads (per the 2.1.88 source microCompact.ts) already waste tokens invisibly. Without native usage analytics, power users either over-invest in custom instrumentation (I've built my own rework logger and session tracker) or fly blind. A /usage command with per-session, per-model, per-tool breakdown would make cost-aware routing possible — and would surface exactly the patterns Anthropic wants to address.

This should consolidate the cost/burn issues listed here. Treating this as a rally hub.

The issue notes that plan utilisation percentage isn't available from local JSONL files — it only comes from the \^Gnthropic-ratelimit-unified-*-utilization\ response headers.

I built a workaround for exactly that gap: a local proxy that intercepts Claude Code's API traffic, captures those headers on every response, and writes a one-line status file to \~/.claude/usage-status.md\. Claude can read it on demand or you can inject it into every prompt via a \UserPromptSubmit\ hook.

Won't replace a proper \claude usage\ command — this is a stopgap — but it does give you live 5h/7d utilisation right now without waiting for Anthropic to ship it.

https://github.com/InertiaUK/claude-quota-proxy

the cost estimation is solid for API-key accounting, but on Pro/Max the dollar number is decoupled from what fires the cap. you can read 150M cache tokens, JSONL says $282, the real question is 'do i have any opus messages left in the rolling 5-hour'. response headers (anthropic-ratelimit-unified-*) only stay fresh until the next call. for a 'remaining plan capacity' view rather than cost math, the foundation has to be whatever the web UI polls to render its own usage screen, since that's the only number that matches the rate-limit toast users actually hit.

One product split that would keep this from becoming a giant dashboard: separate historical analytics from launch preflight.

Historical analytics answers:

• Which sessions/projects/models consumed the most tokens?
• Which tools, subagents, or MCP servers created recurring overhead?
• How much cache read/write did a workflow produce over time?

Launch preflight answers a different question:

• Is it safe to start another large agent task right now?
• How much 5h / 7d plan pressure remains?
• Is the current context already too large for a reliable long run?
• Should the agent checkpoint or compact before continuing?

The first can mostly come from JSONL transcript aggregation. The second needs fresh runtime/plan state and should be cheap enough for scripts and remote launchers to call before starting work.

So a useful shape might be:

claude usage history --json
claude usage preflight --json

Where preflight returns only small run-control fields: plan window usage, reset times, active sessions, context pressure, stale/fresh timestamp, and maybe a recommendation enum like ok, checkpoint_first, wait_for_reset, or manual_review.

+1 to this — consolidated visibility is the right ask, and hopefully it lands natively.

In the meantime, for anyone who needs this today: I open-sourced a tool (not affiliated with Anthropic) that reads the local ~/.claude/projects/**/*.jsonl logs and gives you per-prompt cost & token analytics — from the terminal (a CLI) and an optional Streamlit dashboard. Token counts are split by type (input / output / cache read / cache write 5m vs 1h) and priced at API-equivalent cost. Everything runs locally, no API key, nothing leaves your machine.

A few things it answers that came up in this thread and the issues it consolidates:

• which prompts/projects/models actually drive cost (Pareto views);
• how much of your usage is cache reads (on my own history: 97% of token volume — usually the answer to "why are my tokens exploding");
• how the marginal cost of a prompt changes with its depth in the session (the first prompt of a session is by far the most expensive; follow-ups ride the cache).
• many others

Token totals are validated against ccusage.

Live demo : https://prompt-analytics-demo.streamlit.app/
Repo: https://github.com/romainfjgaspard/prompt-analytics-for-claude-code

(If a built-in claude usage ships, that's strictly better — this is a stopgap that also goes one level deeper, to the prompt grain.)

The consolidation here is well-targeted. One angle worth separating from the main request: when running multi-agent pipelines (orchestrator + 3-8 subagents), the cost attribution gap is qualitatively different from the single-session case.

Right now, /cost in the orchestrator shell shows only the orchestrator's token use. Each subagent session is an isolated process with its own context window. So after a 6-agent pipeline run, you have 7 separate cost numbers living in 7 separate terminal scroll buffers, none of which aggregate anywhere. You cannot answer "what did this pipeline actually cost" without manually opening each session log.

The JSONL approach described here works for post-hoc analysis on single sessions. For multi-agent workflows, the missing piece is a way to link subagent session costs back to the parent run - something like a shared run_id or an aggregation hook that the orchestrator can poll. Without that linkage, claude usage would still give you per-session numbers without a way to group them into "this was one logical pipeline run."

A few things that would make the multi-agent case tractable:

• a parent_session_id field in the subagent session JSONL so aggregation tools can group them
• the SubagentStop hook payload carrying final token/cost data for that subagent
• or at minimum, the status line JSON including aggregate_cost_usd as mentioned in issue #48040

Building Claudeverse (claudeverse.ai) - a scheduling and coordination layer for Claude Code agent fleets - so visibility into per-run aggregate cost is the metric we care most about. The workaround right now is reading the hooks output stream and joining against individual session JSONLs, which is fragile across compactions and restarts.

The JSONL transcript path you're describing is real -- the data is there, the tooling isn't.

One pattern that works without waiting for a native command: a small polling script that reads ~/.claude/projects/ on each cycle, aggregates input_tokens + output_tokens + cache_creation_input_tokens + cache_read_input_tokens per session, and writes a spend_log.jsonl. Running it on a cron or as part of a CI wrapper gives you per-session and per-day rollups without touching Claude Code itself.

The cache-aware cost point matters more than most estimates account for. A session with heavy cache hits looks expensive on raw token counts but is 3-10x cheaper than the same context without caching. Any aggregation that ignores cache_creation vs cache_read will produce numbers that feel wrong and erode trust in the tooling.

For multi-agent runs specifically: session-level aggregation isn't fine enough. You want spend attributed to the agent role (orchestrator, reviewer, specialist), not just the session, so you can see which agent pattern is burning quota. That requires tagging at dispatch time, not post-hoc attribution.