{"_id":"@allenwu06/tokenstack","name":"@allenwu06/tokenstack","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@allenwu06/tokenstack","version":"0.1.0","description":"Per-layer Claude Code token attribution — by MCP server, subagent, skill, and tool family. Beyond per-file.","type":"module","license":"MIT","private":false,"bin":{"tokenstack":"bin/tokenstack.mjs"},"engines":{"node":">=20"},"scripts":{"test":"node --test 'test/*.test.mjs'"},"keywords":["claude-code","claude-code-plugin","tokens","cost-attribution","mcp","subagent","observability"],"repository":{"type":"git","url":"git+https://github.com/allenwu-blip/tokenstack.git"},"gitHead":"219a584b2849b713d2d0ee5048d92bbf078de662","_id":"@allenwu06/tokenstack@0.1.0","bugs":{"url":"https://github.com/allenwu-blip/tokenstack/issues"},"homepage":"https://github.com/allenwu-blip/tokenstack#readme","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-wMAg/JJAUOx31IhCYcWJkI9FBNrughfGhojMi3o6QPWFNkWO8paIqqk/zoRFNepFiLPsNaXoKuFp9RvMUR4daw==","shasum":"58ff5359ebdde506c3a70b0e6378c9122717d9a1","tarball":"https://registry.npmjs.org/@allenwu06/tokenstack/-/tokenstack-0.1.0.tgz","fileCount":9,"unpackedSize":34758,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFMz7+8yjzHOd7FCQ4uI0Gjf3UoqNgVOoz8uAfOFxqoxAiBbMJyglok4CNxUBddhr+9oF05bJvHFYGFTYLBny5Hwfw=="}]},"_npmUser":{"name":"allenwu06","email":"allenwu@umich.edu"},"directories":{},"maintainers":[{"name":"allenwu06","email":"allenwu@umich.edu"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tokenstack_0.1.0_1779677605144_0.9083848440356663"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T02:53:25.053Z","0.1.0":"2026-05-25T02:53:25.262Z","modified":"2026-05-25T02:53:25.404Z"},"maintainers":[{"name":"allenwu06","email":"allenwu@umich.edu"}],"description":"Per-layer Claude Code token attribution — by MCP server, subagent, skill, and tool family. Beyond per-file.","homepage":"https://github.com/allenwu-blip/tokenstack#readme","keywords":["claude-code","claude-code-plugin","tokens","cost-attribution","mcp","subagent","observability"],"repository":{"type":"git","url":"git+https://github.com/allenwu-blip/tokenstack.git"},"bugs":{"url":"https://github.com/allenwu-blip/tokenstack/issues"},"license":"MIT","readme":"# tokenstack\n\n**Per-layer Claude Code token attribution — by MCP server, subagent, skill, and tool family. Beyond per-file.**\n\nOther Claude Code token trackers report cost per file or per tool. tokenstack reports cost **per layer**: which MCP server, which subagent, which skill, which tool family is actually eating your context budget.\n\n```text\n══════════════════════════════════════════════════════════════════════════════\n  tokenstack  ·  session cdf67cff-…\n  model: claude-opus-4-7\n──────────────────────────────────────────────────────────────────────────────\n  session-level totals:\n    input:              87.0k\n    output:           3188.4k\n    cache_create:    12131.2k\n    cache_read:      374880.8k\n──────────────────────────────────────────────────────────────────────────────\n  per-layer \"result-tokens\" (cost of tool returns flowing IN):\n\n  Subagents  (104.2k tokens, 103 calls)        ← what main thread SEES\n    general-purpose          101.0k  (92 calls)\n    Trend Researcher           3.2k  (11 calls)\n  File I/O   (36.5k tokens, 150 calls)\n    Read       19.2k  Bash 14.8k  Edit 2.0k  Write 575\n  Web         9.3k tokens, 17 calls\n  Skills        51 tokens, 4 calls\n\n  ▼ subagent INTERNAL work (drill-into 108 .output files)\n     these tokens are the subagents' OWN work — NOT included\n     in the \"Subagents\" return-tokens line above:\n     input:             328.4k\n     output:           1679.9k       ← what main thread DOESN'T see\n     cache_create:    22762.2k\n     cache_read:      404821.2k      ← 4000× the visible return-blob!\n     internal tool-result tokens:  1474.0k\n     internal tool calls:             3850\n     top 5 most-expensive subagent runs (by cache_read):\n       a7e5784f195a9e651     cache_read= 40.1M  output= 47.7k  tools=192\n       a816f4b671e96f18f     cache_read= 32.6M  output= 86.5k  tools=151\n       …\n══════════════════════════════════════════════════════════════════════════════\n```\n\n## Install\n\n### As a Claude Code plugin (recommended)\n\n```bash\n# In Claude Code\n/plugin marketplace add anthropics/claude-plugins-community   # once\n/plugin install tokenstack@claude-community                   # when accepted\n```\n\nUntil accepted into the community marketplace, install from this repo:\n\n```bash\n/plugin marketplace add https://github.com/allenwu-blip/tokenstack\n/plugin install tokenstack\n```\n\nOr load locally for development:\n\n```bash\nclaude --plugin-dir /path/to/tokenstack\n```\n\nThen in any session, invoke:\n\n```text\n/tokenstack:budget\n```\n\nYou'll also get a per-turn one-line JSON summary written to\n`~/.claude/tokenstack/<session-id>.log` automatically.\n\n### As a standalone CLI\n\n```bash\nnpm install -g @allenwu06/tokenstack\ntokenstack                                    # auto-detect latest session\ntokenstack ~/.claude/projects/.../<session-id>.jsonl\ntokenstack --json                             # machine-readable\n```\n\nOr zero-install:\n\n```bash\nnpx -y @allenwu06/tokenstack\n```\n\n(Note: the npm package is **scoped** to `@allenwu06` because the bare name `tokenstack` was already taken on npm. The bin command after install is still `tokenstack`.)\n\n## What it measures (honestly)\n\n- **Session-level totals** are exact — they're summed from the `usage` field of every assistant message in the transcript.\n- **Per-layer \"result-tokens\"** are an *approximation* — chars / 4 of each `tool_result` content block, attributed to the layer of the tool that produced it (MCP server / subagent / skill / file I/O / web / other). Real BPE varies, so treat layer numbers as a relative-comparison signal, not a billing number.\n- **Subagents** are reported on TWO axes: (a) the result blob flowing back from a `Task`/`Agent` call (shown in the \"Subagents\" line, attributed by `subagent_type`), and (b) the subagent's own internal work (shown in the \"subagent INTERNAL work\" section, aggregated across all `.output` files in `/private/tmp/claude-*/.../tasks/`). The internal work is typically 1000–4000× larger than the return blob — that's the gap other trackers miss.\n- **MCP servers** are pulled from the `mcp__<server>__<tool>` naming convention.\n- **Skills** are attributed via the `Skill` tool's `tool_result` size — note this captures the skill's *return* cost, not the skill's expanded-prompt content (which is delivered via system reminders, not tool_results). This is a known v1 gap.\n\n## How it works\n\n1. Every Stop hook fires at the end of a turn.\n2. The hook receives the session's `transcript_path` and parses the JSONL.\n3. For each `tool_use` in an assistant message, we record its ID and layer.\n4. For each `tool_result` in a user message, we attribute its content size to the matching tool's layer.\n5. Summary is appended to `~/.claude/tokenstack/<session-id>.log` (one JSON per turn).\n6. `/tokenstack:budget` re-parses on demand and prints the full table.\n\nNo network. No telemetry. The plugin writes only to `~/.claude/tokenstack/` on your machine.\n\n## Roadmap\n\n- **v0.1**: main-thread attribution + Stop hook + `/budget` slash command. ✅\n- **v0.2 (current)**: drill-into-subagent-internals — parses each subagent's own `.output` JSONL and surfaces aggregate internal-work cost + top-N most-expensive subagent runs. ✅\n- **v0.3**: HTML report export + per-subagent-type drill-down (map .output files to subagent_type via timestamp/content matching).\n- **v0.4**: predictive pre-tool warnings — PreToolUse hook that blocks expensive Reads before they happen.\n- **v1.0** (paid tier): team / multi-user rollup, per-org cost attribution dashboard hosted at tokenstack.dev.\n\nThe OSS plugin is free under MIT, forever. The paid tier — when it exists — is a hosted multi-user dashboard, not a feature gate on the local tool.\n\n### Why drill-into matters\n\nMain-thread attribution sees only the *return-blob* of a subagent call (typically a few thousand tokens). The subagent itself may have run hundreds of internal tool calls, read megabytes of context, and burned tens of millions of cache_read tokens on its own. In real sessions we've measured **subagent internal work running 1000–4000× larger than the return-blob** that the main thread sees. tokenstack v0.2 is the only Claude Code token tracker that surfaces this gap.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n## Feedback\n\nOpen an issue at https://github.com/allenwu-blip/tokenstack/issues. Real\nmisattributions and missing layers are the most useful thing you can report.\n","readmeFilename":"README.md","_rev":"1-f1d6ba719d2f81110ad3ebbe1d13f9cc"}