[FEAT] Session-audit CLI (ccusage-style) packaged as a Claude Code plugin + skill #2

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)

• Layer 1: CLI surface (feat(cli): token analytics — session audit + sessions inventory #1, merged)
• CLI ergonomics: unify flags/UX in ccusage style (CLI: unify command surface in ccusage style (flags/ergonomics, not scope) #4)
• Layer 2: plugin packaging ([FEAT] Layer 2: package the CLI as a Claude Code plugin (marketplace + plugin.json + skills) #3)
• Parser fix applied locally, drop priceFamily stopgap, 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)
• CI: typecheck / lint / test on push + PR (CI: typecheck / lint / test on push + PR #6)
• Fork hygiene: README banner + upstream sync policy (Fork hygiene: README banner + upstream sync policy #7)
• Releases: tags + CHANGELOG (Releases: tags + CHANGELOG, optional npx bin #8, npx bin → follow-up)