TokenGem/README.md

💎 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.

_{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:

$ 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.

Install in 90 seconds

1. Download TokenGem‑1.0.0‑macOS.dmg (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 — 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:

Project	What it does in TokenGem	Pinned	License
RTK	Compresses shell command output before it enters context	v0.48.0 · fde0a8f	Apache‑2.0
Ponytail	Injects a minimal‑code ruleset so the agent writes less	v4.9.0 · 0a4dd63	MIT
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/, full notices in 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 and read it.

_{Made with care by BigMarc}