# đź’Ž TokenGem
### Make your Claude Code token tools cooperate — and prove what they saved
**TokenGem is the orchestration + measurement layer for AI coding-agent token tools.**
One router instead of three fighting hooks. A baseline frozen from **your own sessions**.
A verdict in your menu bar — green or red, measured, never estimated.
[](https://github.com/BigMarc/TokenGem/releases/latest)
[](https://github.com/BigMarc/TokenGem/releases/latest)
[](#pricing)
Native macOS menu‑bar app · Node CLI · localhost‑only dashboard — a 1.6 MB DMG, no installer, no account, no daemon phoning home
---
## Why TokenGem?
Context is what your Claude Code bill is made of, and the open‑source tools that shrink it are
excellent — **RTK** compresses shell output, **Ponytail** keeps generated code minimal, **Graphify**
stops the agent 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, so together they silently no‑op,
double‑process, or undo each other's work — while your hooks keep *looking* installed.
And even when they work, **savings aren't additive**. RTK's own issue tracker documents a case
where compression cut input tokens and *raised* total cost 18% — shorter input provoked longer
answers, and output tokens cost roughly **5Ă— input** on every current Claude model. TokenGem fixes
the conflict, then measures the result on your machine, against your own before‑numbers.
> 🧠**One router, one hook** · 📊 **Measured vs your baseline** · 🚨 **Red when net‑negative** · 🍎 **Native macOS app**
## Features
| | |
|---|---|
| 🧠**One hook instead of three** | A single `PreToolUse` router dispatches each command to exactly one owner — Graphify's index when fresh, RTK where an equivalent exists, untouched pass‑through otherwise. Nothing double‑processes silently. |
| 📊 **Ground‑truth measurement** | A mandatory baseline from your last 20 real sessions, then a local ledger of every routed command: tokens in, tokens out, **net cost per assistant turn**. |
| 🚨 **The net‑negative alarm** | If compression is provoking more output than it saves, the menu bar turns red and names the profile to switch to. A tool that admits when it isn't helping is the one worth paying for. |
| 📦 **Pinned, isolated installs** | Upstream tools run at audited, pinned versions inside `~/.tokengem/runtime/` — never your global Python, npm, or Cargo. Bumps ship only after regression tests pass. |
| 🪄 **Profiles** | Balanced · Maximum savings · Index‑only — switch from the menu bar; the ledger records which was active for every event. |
| 🩺 **Doctor & repair** | `tokengem doctor` shows every hook registration and who owns it; one‑click **Repair install** for the day a Claude Code update breaks a hook. |
| 🗑️ **One‑button exit** | `tokengem uninstall` restores your pre‑install settings **byte for byte** and deletes the managed runtimes. No trace. |
## We don't estimate your savings. We read them.
Most tools in this category show a percentage computed once, on someone else's machine, and pinned
to a README. TokenGem *sells* measurement, so it measures:
1. **`tokengem baseline`** — mandatory, before install. Reads your real session history and freezes
the median cost per turn. Install refuses to run without it.
2. **Every routed command lands in a local ledger** — raw 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. The three tools' savings are never summed, because they don't
compose. Where a number would be invented, there is a blank — deliberately.
What shows up in your menu bar is the measured verdict. Not a projection. Your numbers, your
machine, your proof.
## Menu bar or terminal — same product
The DMG gives you the native Mac app: a gem showing the measured delta, a session‑by‑session
sparkline against your baseline, profile switching, component health, hook‑conflict detection, and
one‑click repair. Prefer the terminal? It's all 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 (deliberately slow, runs once)
$ 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.
## Pricing
TokenGem is a **one‑time purchase** — no subscription, no telemetry‑driven upsell, no kill switch.
The ladder is devices, not features: every tier gets the whole product.
| | **Solo** | **Duo** | **Studio** |
|---|---|---|---|
| One‑time price | **$59** | **$89** | **$239** |
| Devices | 1 | 3 | 10 |
| Every feature | âś… | âś… | âś… |
| Updates included | 1 year | 1 year | 1 year |
| Licence | **Perpetual** | **Perpetual** | **Perpetual** |
- Your key is verified **offline** — a signed payload checked locally, so activation works on a
plane and a server outage can never take your tool away. A dead laptop doesn't burn a seat.
- Perpetual means perpetual: the key keeps working on the version you bought, even if you never
update again.
- The DMG you download is the **full product** — nothing is crippled while you evaluate it. We'd
rather convince you than lock you out.
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 & Intel, macOS 13+)
2. Open the DMG and drag **TokenGem** to **Applications**.
3. First launch: right‑click → **Open** → **Open** (one time — the binary is ad‑hoc signed while
Developer‑ID notarization is pending). Requires **Node 20+** (`brew install node`); the app
tells you if it can't find it.
4. Click the gem in your menu bar → **Open Dashboard** → follow the four‑command quick start. The
baseline step is the slow one — it's reading your real history, and it only happens once.
## Privacy: nothing leaves your machine
All measurement, every ledger entry, and your baseline stay on your Mac. The dashboard binds to
`127.0.0.1` only. The licence check is a local signature verification — no account, no telemetry.
Every data flow the upstream tools *can* open is listed in one settings view, with switches and a
purge button.
## Honest limits
TokenGem will not help much, and may not help at all, when:
- **Your repos are small** — little context to shrink, 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` shows the collisions, but
adopt‑or‑replace is your decision — nothing is silently clobbered.
- **You want per‑tool dollar attribution.** Numbers are reported at the confidence the
instrumentation supports, and no further.
One published data point to calibrate: Ponytail's *own* benchmark reports **80–94% less code and
42–75% less cost** on single‑shot code‑generation tasks. That's 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.
## FAQ
**Why pay for open‑source tools?**
You're not. The upstream projects stay free, linked below, and unmodified — TokenGem never forks
them. You're buying the part that doesn't exist anywhere else: the deconfliction router, the
baseline‑and‑ledger measurement engine, the rollback guarantee, and the version pins that stop an
upstream Tuesday from silently breaking your setup.
**Will it survive a Claude Code update?**
The hook survives most. When one doesn't, the dashboard shows zero routing events and **Repair
install** re‑asserts it idempotently.
**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 environments were never touched.
**Where do I report a bug or request an agent?**
[Issues](https://github.com/BigMarc/TokenGem/issues) — the [changelog](CHANGELOG.md) 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:
| 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're grateful to the upstream authors and
claim no endorsement, partnership, or affiliation. 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.**
Made with care by BigMarc