token-saver

Cut Claude Code token spend without hurting output quality — a skill, a cheap-model subagent pack, and a real-billing audit tool, installable into any Claude Code setup in one command.

Why (and why not another output-compressor)

Two findings shaped this project:

1. Almost all token spend is reused input. Nate's analysis of 3.77B tokens in one day found 95.7% was reused input — prior turns, tool definitions, files, and tool output re-sent on every request. The lever is keeping the context small and stable, not shaving individual outputs.
2. Compressing tool output doesn't work. JetBrains measured RTK, a hook that rewrites bash output into compact form. Despite "60–90% savings" claims and its own counter reporting 96M tokens saved, real billing went up 7.6% at low effort and ±0% at high effort — the hook touched ~3% of input tokens, Claude Code already truncates long results, and cached re-reads bill at 0.1×.

So token-saver optimizes the levers that actually move the bill:

Lever	How
Keep raw content out of the expensive main context	Skill rules: delegate search/read/run to subagents that return conclusions, not dumps; scoped reads; filtered command output; no re-reads
Stop burning the top-tier model on mechanical work	scout (haiku), reader (sonnet), runner (haiku) agents + a model-routing rule for CLAUDE.md
Preserve the prompt cache (reads bill at 0.1×)	Append-only context habits; no mid-session churn
Measure reality, not counterfactuals	token-audit reads the usage blocks Claude Code itself logs, with cache-aware pricing

Guiding principle (from the article): a token count is a trace, not a scoreboard. Every rule is bounded by "never cause a retry" — one failed cheap attempt costs more than the tokens it saved.

Install as a plugin (recommended)

The repo is a Claude Code plugin and its own marketplace. In any Claude Code session:

/plugin marketplace add bryanvine/token-saver
/plugin install token-saver@bryanvine

That's it — the plugin is enabled at the user level, so it's active in every project and every session. A SessionStart hook injects the token-saver rules into context on startup, after /clear, and after compaction; the skill, agents, and /token-saver:audit command come along with it.

To pin it for a whole team (or manage it declaratively), add to ~/.claude/settings.json (or a project's .claude/settings.json):

{
  "extraKnownMarketplaces": {
    "bryanvine": { "source": { "source": "github", "repo": "bryanvine/token-saver" } }
  },
  "enabledPlugins": { "token-saver@bryanvine": true }
}

Or install manually (symlinks, no plugin system)

git clone https://github.com/bryanvine/token-saver.git
cd token-saver
./install.sh        # symlinks skill + agents into ~/.claude
./tests/run-tests.sh

./install.sh --uninstall removes exactly what it installed. Set CLAUDE_DIR to install elsewhere. The manual route doesn't install the every-session hook; optionally append rules/model-routing.md to your ~/.claude/CLAUDE.md so model routing applies even when the skill isn't loaded.

Use

• Every session (plugin install) — nothing to do; the rules are injected at session start automatically.

• Skill — type /token-saver (manual install) at session start, or it auto-triggers when you ask to save tokens/cost.

• Agents — Claude delegates automatically once the rules are active, or ask directly: "use scout to find where X is defined", "have runner run the tests".

• /token-saver:audit (plugin install) — cache-aware report of where tokens actually went; accepts --project name --days N --json.

• Audit — see where tokens actually went:

  ./bin/token-audit                      # all projects, last 30 days
  ./bin/token-audit --project myapp --days 7
  ./bin/token-audit --json               # machine-readable

  Reports per-model input/output/cache-read/cache-write tokens, cache-aware cost, reused-input share, what the same traffic would have cost without caching, and the most expensive sessions.

Layout

.claude-plugin/plugin.json             plugin manifest
.claude-plugin/marketplace.json        makes this repo installable as a marketplace
hooks/hooks.json, hooks/session-start.sh   injects the rules into every session
commands/audit.md                      /token-saver:audit slash command
skills/token-saver/SKILL.md            the enforced session rules
skills/token-saver/scripts/token-audit.py
agents/{scout,reader,runner}.md        cheap-model subagents (haiku/sonnet)
rules/model-routing.md                 CLAUDE.md snippet: model tiers for delegation
install.sh / tests/run-tests.sh        manual (non-plugin) install + test suite
bin/token-audit                        convenience symlink to the audit script

Python 3.8+ stdlib only; no dependencies, no network calls, nothing leaves your machine.

License

MIT — see LICENSE.