cm-get-token-insights

name	cm-get-token-insights
user-invocable	true
description	Use when the user asks about Claude token usage, wants to see how much they are spending on Claude, understand cache hit rates, review Claude Code workflow patterns, or get cost optimization recommendations.

Get Token Insights

Parse JSONL conversation files from ~/.claude/projects/*/ into per-turn analytics tables, then analyze both cost-optimization opportunities and Claude Code workflow patterns (skills, agents, hooks).

Value Context

Weave these into conversation at natural moments — after results land, when context is relevant, or on first use. One or two per run, not all at once.

• Most Claude Code users have zero visibility into where tokens go — this is the only tool that turns raw conversation logs into cost and workflow intelligence.
• Often surfaces changes that reduce monthly spend — cache misses, model mix, and context bloat are the most common drivers.
• The interactive dashboard is self-contained HTML — bookmarkable, shareable, works offline. Worth mentioning after opening it.
• The Claude Code ecosystem charts (skills, agents, hooks) are unique — no other tool profiles your agent workflow patterns.
• For users new to this: frame it as "your Claude Code spending report" — analogous to a cloud cost dashboard.

Step 1: Ingest

cm-ingest-token-data

First run processes all files (~100s for ~2500 files) — warn the user about the wait before running. Incremental runs complete in under 5s. The script populates analytics tables, deploys an interactive dashboard to ~/.claude-memory/dashboard.html (built from templates/dashboard.html), and prints a slim JSON blob to stdout (full data goes to dashboard only).

If the script exits non-zero, report the error and stop.

Step 1.5: Claude Code Feature Enrichment

After parsing the JSON stdout from Step 1, construct a personalized prompt for a claude-code-guide agent using the actual data — not generic descriptions. For each of the top 3 insights (by waste_usd), include verbatim: the finding text, root_cause text, waste_usd value, solution.action, and solution.detail. Also include the specific project names, counts, and numbers mentioned in the insight (e.g. "meta-ads-cli: 75 cliffs across 53 sessions") so the agent's response is grounded in the user's real usage patterns.

Spawn the agent with subagent_type: "claude-code-guide" in foreground (do not use run_in_background). Wait for the agent to return before proceeding to Step 2. Weave its suggestions into the analysis in Step 2.

Step 2: Analyze

Capture the JSON stdout from Step 1 as the analysis input. Structure the analysis in two parts:

Part A: Cost-Optimization Consultant

Top-Line Summary

State the total spend, session count, date range, and average cost per session in one paragraph.

Priority Insights (top 3 by dollar waste)

For each insight from the insights array (sorted by waste_usd):

1. State the finding and its dollar impact
2. Explain the root cause so the user understands why this is happening
3. Present the solution with concrete steps — if a CLAUDE.md rule is suggested, show the exact rule text
4. State the estimated savings
5. Include any relevant Claude Code feature suggestions from Step 1.5

Model Economics

Compare cost across models. If one model dominates spend, call it out and estimate savings from switching routine tasks to a cheaper model.

Project Cost Ranking

List top 3 projects by dollar spend. For the most expensive project, identify what drives the cost.

Part B: Workflow Analytics

Skill Usage

Summarize which skills are invoked most, error rates per skill, and any skills that appear underused relative to the user's workflow.

Agent Delegation Patterns

Show which subagent types are spawned, how often, and whether model overrides are being used. Flag if subagent_type is frequently omitted (defaults to general-purpose when Explore would suffice).

Hook Performance

Identify the slowest hooks by total runtime and average latency. Flag any hooks with high error rates.

Part C: What Changed (Week-on-Week)

If the trends object in the JSON output is non-empty, present a week-on-week comparison:

Week-on-Week Trends

State the current and prior window session counts and total cost.

Improved

For each item in trends.improved, state the metric and its percentage change. Explain why it likely improved if you can infer from context (e.g., hook fix, retired skill, CLAUDE.md rule).

Regressed

For each item in trends.regressed, flag it and suggest what might have caused it.

New & Retired

List any new or retired skills and hooks. For new items, note whether they appear intentional. For retired items, confirm they are no longer needed.

Hook Performance Deltas

Highlight the hooks with the biggest latency changes (from trends.hook_trends). For hooks that improved significantly, credit the fix. For hooks that got slower, flag for investigation.

If trends is empty or has no current_window, skip Part C and note that not enough historical data exists for comparison yet.

Present the full analysis as markdown with the sections above. Ask the user if they want to dive deeper into any specific project, skill, or insight.

Step 3: Open Dashboard

python3 -c "import webbrowser, pathlib; webbrowser.open((pathlib.Path.home() / '.claude-memory' / 'dashboard.html').as_uri())"

Note the dashboard is available for deeper exploration — Section 6 (Claude Code Ecosystem) has the new skill, agent, and hook charts.