Problem
claude-devtools is GUI-first: you browse sessions in the Electron app (or the standalone HTTP UI). But a large part of the target audience lives in the terminal — and in Claude Code itself. The ecosystem has ccusage for macro cost aggregates (daily/monthly/blocks), yet nothing answers the micro question: for this one session, where inside the agent loop did tokens actually leak, and what was wasted?
Concretely, there is no terminal/agent-consumable way to get:
- a per-turn / per-round token ledger from session JSONL (input vs cache_read vs cache_write vs output, context growth, reread share — in one recent 2-hour session, 94% of 25M billed tokens were context re-reads);
- waste findings: duplicate tool calls, failed calls, oversized tool outputs, context-growth spikes ("agent scanned the whole disk"), dead prompt caching, thinking-heavy turns;
- slow-subagent flags (a subagent running > 5 min is worth questioning);
- a sessions inventory across projects: duration, models used, token totals (i.e. "which sessions ran 2h+ and on which model" — currently not visible anywhere).
Proposal
Two layers:
1. A CLI surface reusing machinery the repo already has — parseJsonlFile / deduplicateByRequestId, pathDecoder, SubagentResolver are all Electron-free, so this adds zero coupling to the app:
pnpm analyze:session <file.jsonl> | --project <dir> --last # ledger + findings + subagents + est. cost
pnpm analyze:sessions [--min-minutes N] [--sort duration|tokens|date] [--json]
Merged: #1 — src/cli/, ~1.2k lines incl. vitest coverage, built on the existing parser stack.
2. Claude Code plugin + skill packaging, so the analysis is consumable by Claude Code itself — the agent can run the audit on the current session and reason about its own waste:
.claude-plugin/marketplace.json at the repo root + .claude-plugin/plugin.json for a session-audit plugin;skills/audit-session/SKILL.md — when to run the audit, how to read the ledger/findings, what to recommend (deny rules for culprit commands, splitting long turns, slimming the parent context);- slash-command wrappers (
/audit-session, /sessions-inventory) with allowed-tools pre-approving the CLI invocation;
- install becomes:
/plugin marketplace add axisrow/claude-devtools → /plugin install session-audit@…; CI-checkable via claude plugin validate.
Reference: https://code.claude.com/docs/en/plugins.md, https://code.claude.com/docs/en/plugin-marketplaces.md
Why it fits the project
This is priority #2 from CONTRIBUTING ("context engineering insight — how tokens flow through a session") extended to the place where the insight is actionable: the terminal, where the sessions are produced. It also covers headless environments (SSH/docker) where the Electron app can't run.
Prior art / non-goals
- ccusage answers a different question (macro cost aggregates across days/months/billing windows, many agent sources). Complementary, not a replacement; no published Claude Code plugin wrapping a per-session audit CLI is known to me — this would fill that gap.
- Not proposing provider-specific billing logic in v1 — findings and ledger are provider-agnostic (exact
usage fields from JSONL); cost estimation is optional and pricing-table based.
Roadmap (fork takeover — upstream dormant since 2026-05)
Problem
claude-devtools is GUI-first: you browse sessions in the Electron app (or the standalone HTTP UI). But a large part of the target audience lives in the terminal — and in Claude Code itself. The ecosystem has ccusage for macro cost aggregates (daily/monthly/blocks), yet nothing answers the micro question: for this one session, where inside the agent loop did tokens actually leak, and what was wasted?
Concretely, there is no terminal/agent-consumable way to get:
Proposal
Two layers:
1. A CLI surface reusing machinery the repo already has —
parseJsonlFile/deduplicateByRequestId,pathDecoder,SubagentResolverare all Electron-free, so this adds zero coupling to the app:Merged: #1 —
src/cli/, ~1.2k lines incl. vitest coverage, built on the existing parser stack.2. Claude Code plugin + skill packaging, so the analysis is consumable by Claude Code itself — the agent can run the audit on the current session and reason about its own waste:
.claude-plugin/marketplace.jsonat the repo root +.claude-plugin/plugin.jsonfor asession-auditplugin;skills/audit-session/SKILL.md— when to run the audit, how to read the ledger/findings, what to recommend (deny rules for culprit commands, splitting long turns, slimming the parent context);/audit-session,/sessions-inventory) withallowed-toolspre-approving the CLI invocation;/plugin marketplace add axisrow/claude-devtools→/plugin install session-audit@…; CI-checkable viaclaude plugin validate.Reference: https://code.claude.com/docs/en/plugins.md, https://code.claude.com/docs/en/plugin-marketplaces.md
Why it fits the project
This is priority #2 from CONTRIBUTING ("context engineering insight — how tokens flow through a session") extended to the place where the insight is actionable: the terminal, where the sessions are produced. It also covers headless environments (SSH/docker) where the Electron app can't run.
Prior art / non-goals
usagefields from JSONL); cost estimation is optional and pricing-table based.Roadmap (fork takeover — upstream dormant since 2026-05)
priceFamilystopgap, close upstream PR fix(parser): parse short model ids without date suffix matt1398/claude-devtools#235 (Apply parser fix locally, drop priceFamily stopgap (carried in fork) #5)