{"_id":"@asmitbohra/tokenscope","name":"@asmitbohra/tokenscope","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@asmitbohra/tokenscope","version":"0.1.0","description":"Token profiler for Claude Code sessions — measures where your tokens actually went and finds waste.","type":"module","bin":{"tokenscope":"dist/cli.js"},"engines":{"node":">=18.0.0"},"scripts":{"audit":"node src/cli.ts","build":"tsc -p .","prepublishOnly":"npm run build"},"keywords":["claude-code","tokens","profiler","cost","llm","context","optimizer"],"author":{"name":"Asmit Bohra"},"repository":{"type":"git","url":"git+https://github.com/AviVAvi/TokenScope.git"},"license":"MIT","devDependencies":{"@types/node":"^26.1.1","typescript":"^7.0.2"},"gitHead":"12bec388849435e9ac9b32b8f62e77a4ef48d1c2","_id":"@asmitbohra/tokenscope@0.1.0","bugs":{"url":"https://github.com/AviVAvi/TokenScope/issues"},"homepage":"https://github.com/AviVAvi/TokenScope#readme","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-OBAyClfliGaVQzXwp0W1p8bmckp/iuZKMTB4skrTQwTQIGlDIRollD3QWHh5NuGY2QyexvyRSTCBMsPBTE9nTA==","shasum":"6f3e02ca2dc59f639c60552bfbd21239cf365526","tarball":"https://registry.npmjs.org/@asmitbohra/tokenscope/-/tokenscope-0.1.0.tgz","fileCount":31,"unpackedSize":156195,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCVOHszn22J7IxePLHz20v5kCp3S6lvnNNzpNJ3OPCjJwIgLsynX4gLaJPMEpnQZiZRLEjgnGcD895mcTaUCls+pLU="}]},"_npmUser":{"name":"asmitbohra","email":"asmitbohra@gmail.com"},"directories":{},"maintainers":[{"name":"asmitbohra","email":"asmitbohra@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tokenscope_0.1.0_1784793123448_0.2764129652780658"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-23T07:52:03.265Z","0.1.0":"2026-07-23T07:52:03.575Z","modified":"2026-07-23T07:52:03.819Z"},"maintainers":[{"name":"asmitbohra","email":"asmitbohra@gmail.com"}],"description":"Token profiler for Claude Code sessions — measures where your tokens actually went and finds waste.","homepage":"https://github.com/AviVAvi/TokenScope#readme","keywords":["claude-code","tokens","profiler","cost","llm","context","optimizer"],"repository":{"type":"git","url":"git+https://github.com/AviVAvi/TokenScope.git"},"author":{"name":"Asmit Bohra"},"bugs":{"url":"https://github.com/AviVAvi/TokenScope/issues"},"license":"MIT","readme":"# tokenscope\n\nA token **profiler** for Claude Code. It parses the session transcripts Claude Code already writes to disk (`~/.claude/projects/**/*.jsonl`) and tells you where your tokens actually went — and what to change to spend fewer of them.\n\n> ccusage tells you *what* you spent. tokenscope tells you *why* — and (soon) proves the fix worked.\n\n## Why a profiler, not an estimator\n\nPredicting what a task *will* cost is guesswork — agent runs vary 3–5x on the same prompt. But every session's real usage is already recorded with per-request precision (input, output, cache reads/writes, per tool call). Measuring beats guessing, so v1 measures.\n\n## Usage\n\n```bash\nnpx @asmitbohra/tokenscope            # overview of every project + top waste findings\nnpx @asmitbohra/tokenscope glow-os    # per-session breakdown for one project\nnpx @asmitbohra/tokenscope codemap .  # generate CODEMAP.md for a repo\n```\n\nOr install globally for the short command:\n\n```bash\nnpm i -g @asmitbohra/tokenscope   # then: tokenscope, tokenscope <project>, tokenscope codemap .\n```\n\nNo runtime dependencies; Node ≥ 18. From a clone, the TypeScript source also runs\ndirectly on Node ≥ 23.6:\n\n```bash\n# Overview of every project + top waste findings\nnode src/cli.ts\n\n# Per-session breakdown for one project (name substring match)\nnode src/cli.ts glow-os\n\n# Generate CODEMAP.md — a signatures-only map of a repo the agent can read\n# instead of exploring whole files\nnode src/cli.ts codemap path/to/repo\n```\n\n### The `/tokenscope` skill (judgment layer)\n\nThe CLI is deliberately deterministic — it measures, it never guesses. The skill adds\nthe judgment layer: a Claude Code session that runs the profiler, reads your project's\nCLAUDE.md and recent prompts to understand the *workflow*, and then tells you which\nrecommendations to apply and which ones are scoring deliberate cost as waste.\n\nInstall (copies into your personal skills directory):\n\n```bash\ncp -r skills/tokenscope ~/.claude/skills/tokenscope\n```\n\nThen in any Claude Code session: `/tokenscope` (or just ask for a token audit).\n\n### Tuning to your workflow (`.tokenscope.json`)\n\ntokenscope scores context *hygiene*, not value — it has no model of your workflow and\ncan't distinguish \"expensive because wasteful\" from \"expensive because verification is\nthe product\". Drop a `.tokenscope.json` in a project root to teach it:\n\n```json\n{\n  \"verification\": true,\n  \"mute\": [\"split-sessions\", \"front-load-specs\"]\n}\n```\n\n`\"verification\": true` suppresses output-filtering advice (truncating output you're\nmeasuring manufactures false confidence). `\"mute\"` silences any recommendation by id.\n\n## What it reports\n\n- **Per-project / per-session totals** — requests, context tokens (input + cache read + cache write), output, and API-equivalent cost using real model pricing incl. cache multipliers (reads 0.1×, writes 1.25×/2×).\n- **Context Score (0–100, A–F)** — per-project hygiene grade from five measured signals: cache efficiency (30), error rate (20), re-read waste (20), compaction churn (15), MCP hygiene (15). High spend ≠ low score; only *waste* costs points. Each component also shows its approximate **dollar impact**, because hygiene points and dollars diverge — cache efficiency usually dominates real cost.\n- **Structural detector** — stats hot files on disk: a 5,000-line append-only doc that gets fully re-read every session is a *structure* problem (no cheap entry point), so it gets a head/archive-split recommendation with the measured math, not a \"add summaries\" platitude.\n- **Recommendations** — every finding maps to a concrete fix with your own numbers as evidence: paste-ready CLAUDE.md blocks (key-file summaries, environment notes classified from your actual error messages, output-filtering rules), `claude mcp remove` commands for servers you configured but never call, and session-hygiene advice.\n- **Codemap** — generates `CODEMAP.md`, a signatures-only skeleton of a repo (files, exports, functions, line anchors) that agents can consult instead of reading whole files.\n- **MCP audit** — cross-references servers in `~/.claude.json` against tool calls in transcripts to find schema-tax with zero payoff.\n- **Context by tool** — how many tokens each tool (Read, Bash, Grep, MCP tools…) injected into context.\n- **Waste findings:**\n  - `repeated-read` — same file read 3+ times in a session\n  - `huge-read` — single file read worth 15k+ tokens\n  - `error-loop` — 5+ failed tool calls (each retry re-bills the growing context)\n  - `verbose-commands` — shell output flooding the context\n  - `low-cache-hit` — sessions where prompt caching mostly missed\n  - `compaction-churn` — sessions that outgrew the context window repeatedly\n\n## Accuracy notes\n\n- Token totals and cost come from the API's own `usage` objects in the transcript — exact.\n- Per-tool context sizes are estimated at ~4 chars/token from tool-result payloads — approximate, clearly a lower bound on their total cost (content re-bills on every subsequent request until cached/compacted).\n- \"API-equivalent cost\" is what the usage would bill via the API; subscription plans prepay this, so read it as *value consumed*, not a bill.\n\n## Roadmap\n\n- **v1 (done):** profiler — measure and diagnose.\n- **v2 (done):** optimizer — Context Score, recommendations engine with paste-ready fixes, MCP audit, error classification.\n- **v2.x (done):** structural detector, dollar-ized score, `.tokenscope.json` intent config, codemap generator.\n- **v2.y:** verified savings — before/after comparison once fixes are applied.\n- **v3:** understanding — task-scoped file prediction trained on the measured history the parser already collects (prompt → files-touched pairs are free ground truth); Codex + other CLI agents.\n\n## Layout\n\n```\nsrc/\n  cli.ts        entry point / project discovery / commands\n  parser.ts     JSONL transcript → structured session data\n  analyzer.ts   metrics + waste-finding heuristics\n  score.ts      Context Score (0-100, with $ impact per component)\n  recommend.ts  findings → evidence-backed fixes (structure-aware)\n  codemap.ts    CODEMAP.md generator (signatures-only repo map)\n  mcp.ts        configured-vs-used MCP server audit\n  report.ts     terminal rendering\n  pricing.ts    model pricing + cache multipliers\n```\n","readmeFilename":"README.md","_rev":"1-edc7902a23362133c9adfcaaca544d83"}