TokenGem/CHANGELOG.md

Changelog

All notable changes to TokenGem are documented here. Upstream tool version bumps are called out explicitly, because they are the changes most likely to affect routing behaviour.

[1.0.0] — 2026-09-04

First public release.

The menu-bar app

• Native macOS app (universal binary, macOS 13+): measured net cost-per-turn delta in the menu bar, red when net-negative; panel with session-by-session sparkline against the baseline median, the four deltas verbatim, profile switcher, component health, hook-conflict list, Repair install, and Open Dashboard.
• Starts at login and launches silently; adopts a dashboard server you started yourself and restarts one that dies.
• Upgrades from pre-rebrand builds migrate ~/.codegem → ~/.tokengem once, on first run. A baseline cannot be recaptured, so it is never left behind.

The router

• One PreToolUse hook per agent, owned by TokenGem. Per-command dispatch: Graphify's index when fresh, RTK where an equivalent exists, pass-through otherwise — never double-processing.
• Three profiles: Balanced (default), Maximum savings, Index-only. Switching re-writes the router in place; the ledger records which profile was active for every event.

The measurement engine

• Mandatory baseline capture per agent from real session history before install — install refuses to run without it.
• Continuous local ledger: command, routing path, raw vs. delivered output bytes, per-session token and cost totals, net delta vs. baseline.
• Output-token watch: when compression provokes longer output, the dashboard says so and names the profile to switch to. Net-negative results are never softened.
• Model pricing table for every provider TokenGem can measure, user-overridable via ~/.tokengem/pricing.json; unknown models are reported UNPRICED, never guessed.

Agents

• Claude Code, Codex, Cursor, OpenCode, Copilot, Gemini CLI, Qwen Code — plus proxy mode for apps that call a model API directly (requests forwarded untouched; only token counts recorded).

Upstream pins (see LICENSES/ and upstream.json in the source tree)

• RTK v0.48.0 (fde0a8f) · Apache-2.0
• Ponytail v4.9.0 (0a4dd63) · MIT
• Graphify v0.9.53 (33362d9) · Apache-2.0 (pre-relicense contributions under MIT)

Known limitations

• The binary is ad-hoc signed; Developer-ID notarization is pending, so first launch needs right-click → Open.
• Node 20+ is required for the CLI/dashboard the app supervises.
• Per-tool dollar attribution is reported only where instrumentation supports it; Graphify and Ponytail effects are not inventable and are not invented.