token-savers

token-savers

The token-saving starter pack for coding agents.

English · 简体中文 · 日本語 · 한국어 · Português

You just installed Claude Code or Codex. Now what? Everyone tells you there are tools that cut your token bill in half, but finding them, picking the good ones, and wiring them up correctly takes a weekend.

This repo is that weekend, already done.

Install

Paste this into a fresh Claude Code / Codex / Gemini CLI session:

Read https://github.com/qy177/token-savers/blob/main/INSTALL.md and install everything in it.

The agent detects your host, tells you which tools have no path on it, installs the rest, and verifies each one. No script to trust, no Node version to match — the agent already knows how to run commands on your machine. It will stop and ask you at every choice that actually matters.

If your agent's web fetch stalls on the GitHub URL — some sandboxed CLIs cannot reach it even when your browser can — tell it to clone instead. That path is fast and reliable:

git clone --depth 1 https://github.com/qy177/token-savers.git

Read token-savers/INSTALL.md and install everything in it.

Prefer to do it yourself? INSTALL.md is written for humans too.

What you get

Five tools. Each one attacks a different part of the bill.

	Tool	Cuts	Reported saving	License
1	rtk	Command output before it reaches context	60–90% on common commands	Apache-2.0
2	context-mode	Tool output — keeps raw data out of context entirely	315 KB → 5.4 KB on their demo workload	ELv2 ⚠️
3	ponytail	The code the agent writes in the first place	LOC −54%, tokens −22%, cost −20%	MIT
4	caveman	The agent's own prose	Output −65% avg	MIT / BSL-1.1
5	TOON	Structured data you hand the model	40–60% vs JSON	Apache-2.0

They stack because they touch different surfaces: what goes in (rtk, context-mode, TOON), what the agent does (ponytail), and what comes out (caveman).

The one people get wrong

Installing rtk is not enough. The binary only helps if something actually rewrites your agent's commands to use it. That is what rtk init -g does — it installs a PreToolUse hook that intercepts every Bash call and swaps in the rtk equivalent.

Skip that step and you are relying on the model to remember to type rtk git status. Most setups fail here, and the usual workaround — pasting the whole rtk manual into CLAUDE.md — is worse than doing nothing: that file is re-sent on every single turn, so you pay for the reminder forever.

rtk init -g --dry-run   # see exactly what it will change
rtk init -g             # then do it. it is the whole point.

The hook rewrites every Bash command your agent runs, in every project, so look at the dry run before you commit to it. rtk init --uninstall reverses it.

On Codex this works differently. rtk init --codex writes instruction files rather than a hook, because Codex cannot rewrite tool input yet (openai/codex#18491). rtk still helps there, but it depends on the model choosing to use it. Hook-capable hosts — Claude Code, Gemini CLI, Copilot — get the enforced version.

Pick one for your agent

Both keep large amounts of data out of your context, in different ways.

Your agent	Use	Prerequisite
Claude Code · Codex · Copilot CLI · OpenClaw	headroom — local proxy that compresses traffic on its way to the API	Runs a background daemon; routes traffic through localhost
Pi	open-codebase-index — semantic code search, so the agent stops reading whole files	Bring your own embedding provider (Ollama, GitHub Copilot, OpenAI, Google, or any OpenAI-compatible endpoint)

headroom has no Pi integration — headroom init only supports claude, codex, copilot, and openclaw. That is the reason for the split.

Gemini CLI gets neither. This step simply has no option there. The other five tools still apply; INSTALL.md has the full per-host matrix, including which tools have no path on which agent.

Bonus: not a token saver, still worth it

mattpocock/skills — Matt Pocock open-sourced his .claude directory. 26 skills covering TDD, debugging, code review, and planning. 247k stars, MIT.

It will not lower your bill. It will raise the quality of what you get for it. Two of its skills do help indirectly: handoff compacts a conversation for handover, and wait-what forces the agent to confirm the ask before burning a turn in the wrong direction.

Did it work?

Never take a saving on faith — every tool here ships its own meter.

rtk verify                    # rtk: is the hook actually wired?
rtk gain                      # rtk: tokens saved, by command
headroom savings              # headroom: compression over time
headroom doctor               # headroom: is it even routed? (see below)

/context-mode:ctx-stats       # context-mode: per-tool breakdown

Honestly

A repo that claims savings owes you the caveats.

• Most numbers here are self-reported by each project. Where a measurement is independent or adversarial, this README says so. Run the meters above on your own workload before believing any of it.

• caveman's benefit depends on your workload. caveman measures output −65%. But ponytail's benchmark, which ran caveman as a control arm, measured it at +7% tokens and +3% cost on agentic coding tasks. Both can be true: shortening prose helps when the agent is talking, and does nothing when it is working. If you mostly code, measure before committing.

• headroom is the one step that can leave you worse off. headroom init re-points your agent's model provider at localhost:8787. If the proxy is not actually listening, your agent cannot reach the API at all after a restart — and the proxy logging "listening" is not proof that it bound the port. Check headroom doctor and netstat/lsof before you restart anything. On a fresh install it usually says not routed, which means you are paying full price with extra steps; that is the harmless failure. The other one is not.

• This pack asks you to trust five other projects. Installing it means piping a remote script into a shell (rtk, unless you use Homebrew), running unpinned npm packages via npx, granting lifecycle hooks the right to run on every turn, and — if you take headroom — routing your API traffic through a local proxy. None of that is unusual for developer tooling. All of it is still a decision, and it should be yours rather than an agent's.

• rtk init -g is the biggest silent change here. It installs a hook that rewrites every Bash command your agent runs, in every project, until you remove it. Run rtk init -g --dry-run first and read what it plans to touch.

• context-mode is ELv2, not OSI open source. Free for you; there are restrictions on offering it as a hosted service. caveman's engine runtime is BSL-1.1 (converts to Apache-2.0 in 2030). Everything else is MIT or Apache-2.0.

• Nothing here is affiliated with this repo. These are other people's projects. Star them, not this.

License

MIT. See LICENSE.