# Tokenscope

> 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.

- Skill: `avivavi/tokenscope` (Agent Skill)
- Install (CLI): `npx skillmds@latest add avivavi/tokenscope`
- Raw SKILL.md: https://api.skillmd.com/api/skills/avivavi/tokenscope/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: AviVAvi (https://skillmd.com/u/avivavi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/avivavi/tokenscope

---


# 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.