TokenPincher

Cut your Claude Code & Codex token bill. One line. No app.

TokenPincher is a small, self-contained CLI: a built-in compression engine, good defaults, a stats screen, and a billing gate. No external compression service, no proxy — compression itself runs entirely offline.

Install / run

This is a prototype package, not yet published to npm. From this directory:

npm install
npm run build
node dist/cli.js --help

The CLI checks the npm registry for a newer version at most once every 24 hours (a single unauthenticated GET, cached locally) — this and license validation are the only network calls TokenPincher ever makes.

Commands

• tokenpincher init — installs TokenPincher into Claude Code: a PostToolUse hook on the Bash tool (compresses large Bash output transparently before it reaches the model) and, if you don't already have one, a statusline. Idempotent — safe to run again. Backs up ~/.claude/settings.json first.
• tokenpincher uninstall — reverses init: removes TokenPincher's hook and statusline entries from ~/.claude/settings.json (backs up first). Leaves ~/.tokenpincher data alone — rm -rf ~/.tokenpincher for full cleanup.
• tokenpincher compress [file] — compress a file or stdin, print the result, record stats.
• tokenpincher exec -- <cmd> [args...] (or tokenpincher exec "<cmd>") — run a command, compress its collected stdout, print the result, exit with the child's exit code.
• tokenpincher stats — savings dashboard (tokens saved, $ saved, tier). Add --detail for a per-model and per-technique breakdown (see below).
• tokenpincher statusline — one-line summary, fast enough to run from a shell prompt. Leads with REAL month-to-date spend/tokens aggregated across every Claude Code session transcript on disk (falls back to TokenPincher's own estimated-savings line until real data is available).
• tokenpincher upgrade — open the upgrade page and prompt to save a Pro license key.
• tokenpincher license <key> — save a Pro license key directly.
• tokenpincher mcp — start the TokenPincher MCP server over stdio (tools: tokenpincher_compress, tokenpincher_stats).

There's also a hidden tokenpincher hook command — not meant to be run by hand. init wires it up as the Claude Code PostToolUse command; it reads the hook's stdin JSON, and if the Bash tool's output is long enough and compresses well, replaces it with the compressed version. It never fails loudly: any error, and it exits 0 with no output, so it can never break Claude Code.

Free trial

TokenPincher is free to try for 7 days, full-featured, with no token caps. The trial clock starts the first time you run init, compress, exec, or use the MCP tokenpincher_compress tool. Once it expires, compression pauses — compress and exec pass text through unchanged with a clear notice, instead of silently stopping to work. tokenpincher upgrade unlocks Pro (unlimited, no trial) at any time.

Your savings stats keep displaying after the trial ends — tokenpincher stats and tokenpincher statusline still show everything you saved during the trial, they just make clear compression is paused until you upgrade.

You'll get a desktop notification when 2 days are left in the trial, and again when it ends (best-effort; macOS and Linux only), each with your running savings total and a nudge toward tokenpincher upgrade.

Running alongside other compressors

If another output-compressing tool (e.g. RTK, Headroom) is also wired up via a Claude Code PreToolUse hook, it conflicts with TokenPincher: Bash output often reaches TokenPincher's PostToolUse hook already compressed, so TokenPincher's own reported savings will look artificially low — that's expected, not a bug.

tokenpincher init detects this conflict up front and, on a TTY, asks whether to disable the other tool's hook (<name> conflicts with TokenPincher. Disable its <name> hook? [y/N]) before writing settings — declining or running non-interactively leaves it untouched. If it's left in place, TokenPincher still surfaces the conflict: when another compressor was seen recently (within the last 7 days) and this month's savings are under 10,000 tokens, tokenpincher statusline appends a terse | <name> also active suffix, and tokenpincher stats prints an explanatory note — so the low numbers aren't misread as TokenPincher being broken.

How compression works

src/engine.ts is TokenPincher's own built-in compressor: minifies whole-input JSON, collapses repeated blank lines, dedupes identical consecutive lines, trims trailing whitespace, collapses long whitespace runs, and truncates very long output to a head/tail slice. No network calls, no external service — it always works offline and instantly.

stats --detail

tokenpincher stats --detail prints everything plain stats does, plus a savings receipt broken down by model and by which compression technique did the work:

Savings by model (this month, est.):
  claude-opus-4-1:
    Direct:  ~300 tokens (~$0.00)
    Reuse:   ~600 tokens (~$0.00)
    Total:   ~900 tokens (~$0.00)
  claude-sonnet-4-5:
    Direct:  ~500 tokens (~$0.00)
    Reuse:   ~2,000 tokens (~$0.00)
    Total:   ~2,500 tokens (~$0.00)

Savings by technique (this month, rough est. — chars/4, not calibrated per event):
  Duplicate lines removed      ~75 tokens (50%)
  JSON minified                ~50 tokens (33.3%)
  Whitespace trimmed           ~15 tokens (10%)
  Blank lines collapsed        ~10 tokens (6.7%)

Real usage by model (month-to-date):
  claude-opus-4-1: 6,500 tokens ($0.19)
  claude-sonnet-4-5: 5,250 tokens ($0.03)

Payback: each compressed output saved ~4.3x its direct trim through context reuse
Full session analytics: npx agentgraphed

"Savings by model" and "Real usage by model" are both scoped to this calendar month, same as the rest of stats. "Savings by technique" is a rougher estimate (chars/4, not calibrated against real per-session token/char ratios like the headline "saved" figures) — it's there to show where the savings came from, not to be added into any other total. Missing data (e.g. older stats.json files predate technique tracking) just shows "no data yet" instead of breaking the command.

Token estimates

There are two classes of numbers TokenPincher prints, and they mean different things:

• "saved" figures (tokenpincher stats, the statusline's saved ~... part, compress/exec output) are estimates, marked with a ~ (or an estimate flag in MCP's JSON output). The counterfactual of "what would this have cost uncompressed" is inherently an estimate — Anthropic doesn't publish its tokenizer, so there's no way to compute an exact count outside their API. Where possible, these estimates are now calibrated against real per-session token/char ratios read from Claude Code's session transcript (real API-reported token counts vs. the transcript's character length), rather than a flat chars/4 guess. When no transcript is available, TokenPincher falls back to its own max(chars/4, words*1.32) heuristic — a blend that avoids under-counting dense, code-heavy text.
• "session" figures in the statusline (session N ($X.XX) in the leading format, or the | session: N ($X.XX) suffix in the fallback format) are real numbers reported by Claude Code itself — no ~, no estimation. They come straight from the statusline JSON's cost/context_window fields, or, when those aren't present, directly from the session transcript's message.usage fields. These are what Anthropic's API actually billed.
• month-to-date figures leading the statusline (⚡ 241.9k ($3.62) this month) and the tokenpincher stats "Real usage (all sessions)" section are also real, computed entirely locally by reading Claude Code's own transcript files under ~/.claude/projects/ and summing this calendar month's message.usage across every session. Nothing is sent anywhere — no network call is involved in computing them.

Licensing

Pro is unlocked with a license key purchased via checkout at tokenpincher.io/upgrade (shown after purchase). tokenpincher license <key> (or the tokenpincher upgrade prompt) activates the key against TokenPincher's licensing API at tokenpincher.io and saves it locally. Once activated, the CLI trusts that license offline for 14 days (so stats/statusline never block on a network call), quietly revalidating in the background near the end of that window. If a key is explicitly revoked, you're moved back to the free tier and told so. Network hiccups never demote you or block a command.

NOTICE

See NOTICE — TokenPincher's compression engine is original code.