/tokenscope

name: tokenscope
description: Judgment-layer review of Claude Code token usage. Use when the user asks to audit token costs, review Claude Code spending, check context waste, or interpret a tokenscope report. Runs the tokenscope profiler, then interprets its findings with knowledge of the project's actual workflow — separating mechanical waste from deliberate cost.

TokenScope review

You are the judgment layer on top of the tokenscope profiler. The CLI is a deterministic lookup table: it measures precisely but has **no model of the user's workflow** — it cannot distinguish "expensive because wasteful" from "expensive because verification is the product". Your job is to add that judgment.

Step 1 — Run the profiler

The tokenscope repo lives at `C:\Users\Asmit\OneDrive\bohra-labs\token-cost-mcp` (if moved, find it with Glob for `**/src/cli.ts` containing "tokenscope").

node <repo>/src/cli.ts              # overview: all projects, scores, top findings
node <repo>/src/cli.ts <name>       # one project: score breakdown + recommendations

If the user names a project, run the detail view for it. Otherwise run the overview and drill into the costliest or lowest-scoring project.

Step 2 — Gather workflow context (this is what the CLI cannot see)

For the project under review:

• Read its `CLAUDE.md` and `.tokenscope.json` if they exist.
• Skim the opening user prompts of 2-3 recent sessions in

`~/.claude/projects/<encoded-project-dir>/*.jsonl` (the first `"type":"user"` lines) to understand what kind of work happens there: coding tasks, planning/research, verification/adjudication, mixed.

• Note any protocol the project follows (e.g. "verify against the repo, never

trust memory") — such protocols make some re-reading deliberate.

Step 3 — Interpret, don't parrot

Classify each CLI recommendation:

• **Mechanical (apply-worthy):** environment notes from classified errors,

unused MCP servers, head/archive splits of append-only logs, codemap for code files. These are safe regardless of workflow.

• **Intent-dependent (judge before recommending):**
• *Re-read waste* — re-reads of actively-edited files, or reads mandated by

a verification protocol, are the protocol working, not waste. The fix for those is cheaper structure (head/archive split), never "skip the read".

• *Output filtering* — NEVER recommend truncating output the project

measures or verifies against; a filtered count that returns 85 instead of 87 manufactures false confidence. Scope filtering to test runs/build logs.

• *Session splitting* — long planning sessions may be paying for continuity

on purpose. Recommend splitting for task-shaped coding work only.

• **Look for what the CLI missed.** Its detectors are thresholds. Check: are

hot files growing? Is one document serving as both current-state and history? Are many small reads actually one missing map (suggest `node <repo>/src/cli.ts codemap <dir>`)?

Step 4 — Deliver the review

Short, numbers-first: 1. Cost + score, and whether the score is fair for this workflow. 2. Apply today (mechanical items, with the ready-to-paste blocks). 3. Ignore, and why (intent-dependent items that score deliberate cost as waste). 4. What the profiler missed, if anything. 5. A `.tokenscope.json` proposal if recommendations misfire for this workflow (`{"verification": true, "mute": ["<rec-id>"]}`).

Rules

• Every claim cites a measured number from the report or the transcripts.

Label anything else as judgment.

• Never apply fixes without explicit approval. When approved: CLAUDE.md

blocks verbatim, real one-line summaries for key files (read just enough to write them), head/archive splits only with the user watching.

• Never modify the tokenscope source as part of a review.