# ๐ TokenGem
### Your Claude Code token tools are arguing with each other.
### TokenGem makes them cooperate โ and shows you what they actually saved.
[](https://github.com/BigMarc/TokenGem/releases/latest)
[](https://github.com/BigMarc/TokenGem/releases)
[](https://github.com/BigMarc/TokenGem/releases/latest)
[](https://github.com/BigMarc/TokenGem/releases/latest)
[](#pricing--license-terms)
**[โฌ๏ธ Download the latest DMG](https://github.com/BigMarc/TokenGem/releases/latest)**
A 1.6 MB download. No installer, no account, no daemon phoning home.
---
You already know context is what your Claude Code bill is made of. You may even run the
open-source tools that shrink it โ **RTK** to compress shell output, **Ponytail** to keep the
agent's code minimal, **Graphify** to stop it re-grepping your repo.
Here's the part nobody tells you: **installed side by side, they fight.** All three register a
`PreToolUse` hook on Bash. One rewrites `grep` into its own command, another intercepts the same
command and nudges toward its index, a third injects rules at session start. Run together, they
silently no-op, double-process, or undo each other's work โ and your hooks keep *looking* installed.
And even when they work: **savings are not additive.** RTK's own issue tracker documents a case
where the filter cut input tokens and *raised* total cost by 18% โ because compressed output made
the agent ask more follow-up questions, and output tokens cost roughly **5ร input** on every
current Claude model.
TokenGem is the layer that fixes both problems, and it is the only one that *proves* which one it
fixed for you.
## What TokenGem actually does
| | |
|---|---|
| ๐งญ **One hook instead of three** | TokenGem writes a *single* `PreToolUse` hook โ its router. Each command is dispatched to exactly one owner: Graphify's index when it's fresh, RTK when there's an equivalent, untouched pass-through otherwise. Every event is recorded, so nothing double-processes silently. |
| ๐ฆ **Pinned, isolated installs** | The three upstream tools are installed at audited, pinned versions into `~/.tokengem/runtime/` โ never your global Python, npm, or Cargo environments. A bump ships only after TokenGem's regression suite passes. |
| ๐ **Ground-truth measurement** | Before anything changes, TokenGem reads your agent's own session records and freezes a baseline. Every session afterwards is measured against it: tokens in, tokens out, **net cost per assistant turn** โ the number that survives session-length skew. |
| ๐จ **The net-negative alarm** | If compression is provoking more output than it saves, TokenGem says so โ in red, in your menu bar โ and names the profile to switch to. A tool that admits when it isn't helping is the one worth paying for. |
| ๐๏ธ **One-button exit** | `tokengem uninstall` restores your pre-install settings **byte for byte** and deletes the managed runtimes. Your machine is exactly as it was. |
## We don't estimate your savings. We read them.
Most tools in this category show you a percentage they computed once, on their machine, and
pinned to a README. TokenGem can't afford that honesty problem โ it *sells* measurement, so it
measures:
1. `tokengem baseline` โ mandatory, before install. Reads your last 20 real sessions per agent and
freezes the median cost per turn. **Install refuses to run without it**, because a savings
figure with nothing to compare against is a marketing artifact, not a measurement.
2. Every routed command lands in a local ledger: raw output bytes, delivered bytes, which path
handled it, which profile was active.
3. The Savings view reports the **net delta against your baseline** โ and attribution only where
the instrumentation supports it. Graphify redirects are counted, not invented; Ponytail's
effect is reported as an aggregate. **The three tools' savings are never summed**, because
they don't compose.
What shows up in your menu bar is the measured verdict โ cost per turn vs. your own baseline,
green or red. Not a projection. Your numbers, your machine, your proof.
## The menu-bar app
The DMG gives you the native Mac app: a gem in your menu bar showing the measured delta, a panel
with a session-by-session sparkline against your baseline median, profile switching (Balanced ยท
Maximum savings ยท Index-only), component health, hook-conflict detection, and one-click
**Repair install** for the day a Claude Code update breaks a hook โ that day will come.
Prefer the terminal? The same product is a CLI:
```console
$ tokengem hosts # which agents are on this machine, and what TokenGem can do for each
$ tokengem doctor # pre-flight checks + every hook registration and who owns it
$ tokengem baseline # mandatory: capture your before-numbers (this one is deliberately slow)
$ tokengem install # snapshot โ pinned runtimes โ one router
$ tokengem dashboard # http://127.0.0.1:7801 โ six views, bound to localhost only
```
## Works with the agents you already run
Claude Code ยท Codex ยท Cursor ยท OpenCode ยท Copilot ยท Gemini CLI ยท Qwen Code โ plus a local
**proxy mode** that meters any app calling a model API directly, forwarding requests untouched
and recording only token counts. Run `tokengem hosts` to see exactly what TokenGem can do for
each agent it finds: route and measure, or measure only.
## What leaves your machine: nothing
All measurement, every ledger entry, and your baseline stay on your Mac. The dashboard binds to
`127.0.0.1` only. The license is a signed key verified **locally** โ activation works on a plane,
and a server outage can never take your tool away. Every data flow the three upstream tools *can*
open is listed in one settings view, with switches and a purge button.
## Honest limits
Every tool should publish these. TokenGem will not help much, and may not help at all, when:
- **Your repos are small.** There's little context to shrink and little to index.
- **Your sessions are mostly reasoning**, not file-reading. Compressed `grep` output can't save
what never got read.
- **Your hooks are already hand-tuned.** `tokengem doctor` will show the collisions, but adopt-
or-replace is a decision you get to make โ nothing is silently clobbered.
- **You want per-tool dollar attribution.** RTK's character reduction is measured; Graphify and
Ponytail are reported at the confidence the instrumentation actually supports. Where a number
would be invented, there is instead a blank โ deliberately.
One published data point so you can calibrate expectations: Ponytail's *own* benchmark reports
**80โ94% less code and 42โ75% less cost** across five single-shot code-generation tasks, 3 models,
10 runs per cell (median reported). That is their measurement, not yours โ yours is what the
ledger is for. And the failure mode is real: the 18%-net-*increase* case above is why the
baseline exists.
## Pricing & license terms
**$59. Once.**
- Perpetual licence to the version you bought โ your key keeps working even if you never update.
- Signed key, **verified offline** on up to 3 devices; a dead laptop doesn't burn a seat.
- The DMG you download is the full product โ nothing is crippled while you evaluate it. We'd
rather convince you than lock you out.
- Uninstall is one command and restores your machine exactly. If the product isn't for you, it
leaves no trace.
Questions about licensing โ [open an issue](https://github.com/BigMarc/TokenGem/issues/new).
## Install in 90 seconds
1. **[Download TokenGem-1.0.0-macOS.dmg](https://github.com/BigMarc/TokenGem/releases/latest)**
(1.6 MB, universal โ Apple Silicon and Intel)
2. Open the DMG and drag **TokenGem** to **Applications**.
3. First launch: right-click the app โ **Open** โ **Open** (one time only โ the binary is
ad-hoc signed while Developer-ID notarization is pending, so macOS checks you meant it).
Requires **Node 20+** (`brew install node`) โ the app will tell you if it can't find it.
4. The gem appears in your menu bar. Click it โ **Open Dashboard** โ follow the four-command
quick start. The baseline step is the slow one; it's slow because it's reading your real
history, and it only ever happens once.
## FAQ
**Why pay for open-source tools?**
You're not. The three upstream projects stay free, stay linked below, and stay unmodified โ
TokenGem never forks them. What you're buying is the part that doesn't exist anywhere else: the
deconfliction router (nobody has published a correct merge order for these three hooks), the
baseline-and-ledger measurement engine, the rollback guarantee, and the version pins that stop an
upstream Tuesday from silently breaking your setup.
**Is "buy once" real?**
Yes, with a noun: the licence is perpetual for the version you purchased. There is no subscription,
no telemetry-driven upsell, and no kill switch โ verification is a local signature check.
**Will it survive a Claude Code update?**
The hook survives most; when one doesn't, the dashboard shows zero routing events and the
**Repair install** button re-asserts it idempotently. Upstream tool versions are pinned and only
bump after regression tests pass.
**How do I remove it completely?**
`tokengem uninstall`, then drag the app to the Trash. Settings snapshots in `~/.tokengem/backups/`
are restored byte for byte; your global Python/npm/Cargo environments were never touched.
**Where do I report a bug or request an agent?**
[Issues](https://github.com/BigMarc/TokenGem/issues) โ the changelog is public and each release
notes exactly what changed, including upstream version bumps.
## Under the hood โ and in our debt
TokenGem orchestrates three open-source projects as managed, pinned dependencies. They are named
here on purpose: you'd find them in five minutes anyway, and you deserve to find them in five
*seconds* instead โ after purchase, which is how chargebacks happen.
| Project | What it does in TokenGem | Pinned | License |
|---|---|---|---|
| [RTK](https://github.com/rtk-ai/rtk) | Compresses shell command output before it enters context | v0.48.0 ยท `fde0a8f` | Apache-2.0 |
| [Ponytail](https://github.com/DietrichGebert/ponytail) | Injects a minimal-code ruleset so the agent writes less | v4.9.0 ยท `0a4dd63` | MIT |
| [Graphify](https://github.com/Graphify-Labs/graphify) | Builds a queryable repo knowledge graph so the agent stops re-grepping | v0.9.53 ยท `33362d9` | Apache-2.0 |
Verbatim license texts live in [`LICENSES/`](LICENSES), full notices in
[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md). We are grateful to the upstream authors and
claim no endorsement, partnership, or affiliation with them. TokenGem's router, measurement
engine, dashboard, and licensing are original work.
---
**Stop guessing what your token tools saved.
[Download TokenGem](https://github.com/BigMarc/TokenGem/releases/latest) and read it.**