v0.10.0 — Task categorization, expanded

What's new

categorize now sees every editor, not just Claude Code. Task-intent text is captured from Cursor, Copilot, Gemini CLI and Codex sessions too (#56). Antigravity stays token-only for now.

Task-category dashboard. token-monitor categorize --html cat.html writes a self-contained dashboard — categories, cross-project duplicate work, and org-skill candidates (#58).

Duplicate work, surfaced where you already look. Once you've run categorize, report and the HTML dashboard show a one-line callout: 🔁 N recurring tasks spanning ≥2 projects. Computed read-only from on-device fingerprints — counts and cost only, never labels or raw prompt text.

Privacy floor unchanged: prompts are reduced on-device to ≤8 redacted keyword tokens before anything is stored. Zero new runtime deps. 167 tests.

Install

• npm: npm i -g @ryandemelo/token-monitor@0.10.0
• VS Code Marketplace: search token-monitor, or install the .vsix below

v0.9.0 — Task categorization

Task categorization

New offline categorize command — see what your team uses the agent for, where work repeats across projects, and which recurring tasks are worth codifying as a shared skill.

token-monitor categorize [--days 30] [--threshold 0.4] [--min-cluster 2] [--project <name>] [--source <name>] [--json]

• Clusters sessions by task intent, flags duplicate work across projects, and surfaces org-skill candidates.
• Fully offline & deterministic — no agent, no network. Intent is derived on-device: each session is reduced to ≤8 redacted keyword tokens before anything is written. Structured secrets (emails, API keys, URLs, paths, IPs, UUIDs, connection strings, PEM blocks, key=value) are stripped first; raw prompt text is never stored, printed, or sent.
• High-trust signals (duplicate work, skill candidates) only fire on real prompt-text evidence — no false accusations from tool-only sessions.

Zero new runtime dependencies. 159 tests; CI green on Node 24/25 × Linux/macOS.

Engine: zero-dep IDF-cosine + inverted-index + union-find clustering, default similarity threshold 0.4 (tuned to short-fingerprint cosines).

Install: npx @ryandemelo/token-monitor categorize · VS Code extension auto-updates from the Marketplace · .vsix attached below for manual install.

This is the first slice (claude-code text capture). Next: fan intent capture to the other adapters, team-export rollups, and an opt-in --llm labels-only naming pass.

v0.8.0 — Diagnose & track

Recommendations that name the cause, not just the symptom — and that hold the LLM's own advice accountable (#41, #42).

Cause decomposition (#41)

Findings used to name a symptom ("cache hit low") without the cause. Now each one decomposes its symptom tokens — already collected per session — into disjoint candidate causes and names the dominant lever with its share:

• low cache hit → cold restarts after idle gaps · sessions too short to build cache · context churn (late-session growth re-paid fresh) · steady-state baseline
• high rework → code written without a test gate · broad test failures · stacked correction loops · baseline

cause: cold restarts after idle gaps (58%) rides under each recommendation in report, analyze, and the HTML dashboard, and travels in signed exports — aggregate-only (key/label/tokens/share), never prompt or code. A cause under 15% stays silent rather than over-claim, and the context-churn bucket reuses the exact bloat definition the rest of the tool uses, so a cause never contradicts your own contextBloatShare.

Track LLM recommendations through follow-through (#42, experimental)

analyze --llm gave advice that evaporated. analyze --llm --track makes it accountable: the local agent answers in strict JSON, each intervention is parsed into a tracked finding keyed to the metric it targets, and later report/html runs measure whether the advice actually moved that number — the same follow-through that already grades the built-in recommendations, now with a 🤖 marker.

• Findings keep their original baseline across runs (one tracked number per metric), so improvement is measured from the first time the advice was given.
• The parser tolerates prose- or fence-wrapped JSON and drops anything untrackable instead of failing; a failed agent run records nothing.
• Privacy is unchanged — only the existing aggregate payload (counts, ratios, names) is ever sent. No prompt or code content.

Install: npx @ryandemelo/token-monitor · extension: download token-monitor-0.8.0.vsix below → Extensions: Install from VSIX…

Contributor-wanted: Aider (#38), OpenCode (#39), Windsurf (#12) adapters.

v0.7.0 — Trust & trends

Reconcile against billing data, see direction not just snapshots, and recommendations that benchmark you against yourself (#36, #37, #40).

Reconcile — close the threat-model gap (#36)

token-monitor reconcile --provider anthropic|openai cross-checks the local database against the provider's own usage API (Anthropic Admin API / OpenAI Usage API). Per model: local tokens, org-billed tokens, coverage %. Local ≤ API is the expected state — local > org billing exits 1: inflated or double-counted logs won't reconcile. The admin key (ANTHROPIC_ADMIN_KEY / OPENAI_ADMIN_KEY) is read from the environment for that run only — never stored, never exported. This delivers the mitigation the threat-model docs have promised since v0.3.

Trend reports (#37)

report --trend compares the window against the previous same-length one — spend, cost, cache hit, rework, and the v0.6 signals, each with a direction arrow (green improving / red regressing), plus the top project movers by spend change. The HTML dashboard includes the trend automatically once two windows of data exist.

Recommendations 3.0 (#40)

• Personalized targets — with ≥8 meaningful sessions, targets come from your own top-quartile sessions ("your best sessions already run at 1% cold restarts") instead of static heuristics.
• Honest combined math — overlapping levers are de-overlapped into families (caching / routing / rework), giving one headline: Potential: $18.8k/mo → $8.9k/mo (routing −$9.2k · caching −$712). Recommendations sort by marginal value.
• Realized savings — follow-through now prices the baseline→current move: Realized +$70/mo. The advice proves its own worth.

Install: npx @ryandemelo/token-monitor · extension: download token-monitor-0.7.0.vsix below → Extensions: Install from VSIX…

Contributor-wanted: Aider (#38), OpenCode (#39), Windsurf (#12) adapters.

v0.6.0 — Org rollups & optimization insights

Central cross-team curation, four new optimization signals, and recommendations that prove their worth (#27, #29, #28; prices pinned in #30).

Org rollups (#27)

• Two-level teams.yaml — team: header → indented member: discipline (nested JSON too); flat files keep working
• merge --by team|discipline picks the comparison axis; merge --html org.html writes a self-contained org dashboard from the merged exports
• Identity = signing fingerprint, not the OS username: same-name members on different teams stay distinct, stale exports from the same signer are deduped to the newest (with a warning), and --keys keys.json becomes the naming authority
• Serverless org pattern documented: every team's push targets one drop; the org lead merges the signed files

New optimization signals (#29)

• Context bloat trend — sessions whose late-half context grows ≥2× without cache reads keeping pace → start fresh / compact earlier
• Cold restarts — turns resuming after the ~5-min cache TTL that re-pay their context as fresh input → batch prompts, split idle work
• Model right-sizing — premium-model tokens spent on exploration/conversation turns → route reads to a cheaper tier
• Tool-error hotspots — retry-loop token cost per tool, extending the error-rate table

Each signal is a metric, a one-line summary in report + the dashboard, new analyze tables, and a threshold-gated recommendation tracked by follow-through.

Recommendations 2.0 (#28)

Every fired recommendation now cites the worst 3 sessions that triggered it (session ids, dates, token counts — aggregate-only, never content) and estimates $/month savings if the metric hit its target, priced from your own model mix and the pinned price table (~ when estimates are involved):

→ 43% of spend is premium-model tokens on exploration/conversation turns. …  ≈ $8060/mo
    worst: db0a7d17 (procurement, 2026-05-26, 1.8M premium on exploration/chat) · …

Surfaces in report, analyze, the HTML dashboard, and rides along in signed exports (recommendationDetails). Follow-through baselines keep working — recommendation ids are stable.

Install: npx @ryandemelo/token-monitor · extension: download token-monitor-0.6.0.vsix below → Extensions: Install from VSIX…

v0.5.0 — VS Code-family extension

One extension for VS Code, Cursor, Windsurf, and Antigravity (#13, #23):

• Status bar — work tokens + estimated cost for the current project (1.2M · ~$45), cache hit and rework ratios in the tooltip, warning state when the CLI is unreachable
• Token Monitor: Open Dashboard — the CLI's self-contained HTML dashboard in a webview
• Token Monitor: Collect & Refresh — on-demand re-scan, plus auto-collect on a configurable interval

The extension is a thin UI over the CLI — all parsing, storage, and privacy guarantees stay in @ryandemelo/token-monitor. The tokenMonitor.command setting is machine-scoped, so a workspace can't redirect which binary runs.

Install: download token-monitor-0.5.0.vsix below → in your editor run Extensions: Install from VSIX…. Requires Node ≥ 24 on PATH (default command: npx -y @ryandemelo/token-monitor).

Also in this release: the CLI is on npm as @ryandemelo/token-monitor — plain npx @ryandemelo/token-monitor now works.

v0.4.0 — IDE coverage

token-monitor now reads IDE agent sessions, not just CLI logs. Three new adapters, all zero-dependency:

New adapters

• Cursor (#9, #18) — per-turn input/output tokens from state.vscdb, with tool calls, agent/chat sessions, and workspace attribution. Reads only composer/bubble keys; the auth entries in the same database are never touched (enforced by test). Cursor doesn't persist cache tokens or the resolved backend model — Auto mode reports as cursor-auto.
• Antigravity CLI (#10, #19) — per-LLM-call prompt/cached/output tokens decoded from protobuf blobs with a hand-rolled ~100-line wire-format reader (src/protowire.ts). Per-call model, timestamps, tool-step attribution, workspace + git branch. Conversation text is never decoded — privacy by construction. Vendor-internal schema, so everything fails soft.
• Copilot Chat (#11, #20) — ⚠️ experimental: Copilot records no token usage locally, so counts are estimated from text length (~4 chars/token) and models are suffixed (est). Turn counts, timestamps, tools, and error linkage are real.

Also

• Classifier knows view_file (read) and run_command (shell) tool names
• User-cancelled commands ("context canceled") no longer count as tool errors
• Spike findings with full storage-format field maps documented in #9 and #10

Deferred

• #12 Windsurf adapter — needs a contributor with Windsurf installed (help wanted)
• #13 VS Code-family extension — next milestone

Full pipeline (collect → report → export → verify → merge → html → analyze) covered by e2e tests across all six sources on Node 24/25, Linux + macOS.

v0.3.0 — Team deployment & integrity

Remote rollout

A team lead hosts one config file and sends one line:

npx github:ryandemelo/token-monitor init --from https://example.com/team-config.json

init configures the machine, generates signing keys, runs the first collection, installs the recurring collect+push schedule (launchd/cron), and prints the dev's fingerprint for enrollment. Signed exports then arrive at the lead's HTTPS endpoint or shared path automatically.

Tamper-evident results

Exports are Ed25519-signed over a canonical serialization (built-in node:crypto — still zero dependencies). merge --verify rejects anything modified after signing or unsigned; --keys keys.json pins username→fingerprint to block impersonation. The README documents the threat model honestly: tamper-evident, not tamper-proof — a dev editing their own source logs is out of scope client-side; the provider-API cross-check (roadmap) is that backstop.

Metric accuracy

• User-declined permission prompts are no longer counted as tool errors (they were inflating error rates — 38% on one tool in live data — and could poison rework)
• Interactive prompt tools now classify as conversation, not coding
• analyze warns when rework is high but testing share is ~0 (fix-loop detection needs test turns to see churn)
• reworkRatio vs fixIterations documented side by side

55 tests, CI green on Node 24/25 × Linux/macOS. All changes via reviewed PRs: #14, #15, #16. Closes #3–#8.

Full changelog: v0.2.0...v0.3.0

v0.2.0 — one-command install + LLM-powered analysis

Install (new)

npx github:ryandemelo/token-monitor collect
npx github:ryandemelo/token-monitor report

No clone, no build step. AGENTS.md and llms.txt let any coding agent install and operate it for you — paste this into Claude Code / Gemini CLI:

Install token-monitor from https://github.com/ryandemelo/token-monitor (instructions in its AGENTS.md), run collect and report, and walk me through what my token usage says.

Deep analysis + LLM recommendations (new)

token-monitor analyze — session-level deep dive: most expensive sessions, fix-loop churn, context-heavy sessions (avg tokens fed per turn), per-tool error rates.

token-monitor analyze --llm — pipes an aggregates-only payload into a coding agent you already have (claude/gemini/codex, auto-detected) and returns prioritized interventions citing your actual numbers: the evidence, the workflow change, and the metric to watch. No API keys, still zero dependencies.

Also

• Privacy hardening: gitignored reports/exports/agent context; docs use fictional sample data; --llm privacy boundary documented
• PR-based development workflow with CI gates (42 tests, Node 24/25, Linux + macOS)

Full changelog: v0.1.0...v0.2.0

v0.1.0 — local-first token effectiveness monitor

First public release.

What it does: parses the session logs Claude Code, Gemini CLI, and Codex already write locally, classifies every turn by activity (thinking / exploration / coding / testing / shipping), and reports where tokens actually go — with usage personas and concrete recommendations.

Highlights

• 3 adapters — Claude Code (verified), Gemini CLI (verified), Codex (experimental)
• Activity classification from tool calls + shell commands, cross-vendor
• Metrics — cache hit ratio, rework ratio (spend after first test failure), think:code ratio, model mix, estimated cost
• Personas — Architect, Surgeon, Explorer, Sprinter, Firefighter, Balanced — per project and overall, each with tailored recommendations
• Team rollups — merge command combines privacy-safe member exports into per-discipline reports (team.yaml)
• Follow-through — recommendations store a baseline on first firing; later reports show the measured delta (tracking / improving / resolved)
• HTML dashboard — one self-contained file, no server
• Zero runtime dependencies (built-in node:sqlite), Node ≥ 24; 37 tests, CI on Linux + macOS

Everything stays on your machine: no API keys, no network calls, aggregate numbers only.