Every token counts. Every session is scored.
tokengolf.dev · npm · GitHub
Turn Claude Code token efficiency into a game. Every session is automatically tracked and scored against a dynamic par budget. Work normally. On /exit — a scorecard, achievements, and a score that measures how well you prompt.
Better prompting → fewer tokens → higher score. 60+ achievements. 9 hooks. 4 character classes. Zero config beyond install.
██ 🏆 SESSION COMPLETE
██ ──────────────────────────────────────────────────
██ $0.21 /$3.00 par 14% ⚔️ Sonnet 🥇 Gold
██ 🌟 LEGENDARY
██ ──────────────────────────────────────────────────
██ 🎯 Sniper 🥈 Silver 🔥 No Rest ✅ Clean Run 🧰 Toolbox 🤫 Silent Run
Claude Code Plugin (recommended — auto-updates)
claude plugin marketplace add josheche/tokengolf
claude plugin install tokengolf@tokengolfnpm (alternative — requires hook setup)
npm install -g tokengolf
tokengolf install # patches ~/.claude/settings.jsonHomebrew
brew tap josheche/tokengolf
brew install tokengolf
tokengolf installcurl
curl -fsSL https://raw.githubusercontent.com/josheche/tokengolf/main/install.sh | bashThat's it. Open Claude Code, work normally, /exit — scorecard appears automatically.
npm users get auto-sync — hooks update automatically on version change.
All commands
tokengolf scorecard # last run scorecard
tokengolf stats # career dashboard
tokengolf config # view all config values
tokengolf config emotions emoji # set emotion mode (off, emoji, ascii)
tokengolf config par # view/set par rates per model
tokengolf config floor # view/set par floors per model
tokengolf demo # show all UI states (hud, scorecard, stats)
tokengolf install # patch ~/.claude/settings.json with hooks (npm only)Every Claude Code session is automatically tracked — no setup, no pre-configuration. TokenGolf measures your efficiency against a par budget that scales with your session:
par = max(rate × sqrt(prompts), model_floor)
efficiency = actual_cost / par
Par grows with your session, but sublinearly — early prompts give you room to explore, while pressure builds as the session goes on. Efficient prompts beat par; wasteful ones fall behind. Spend more than par and the run busts — logged as a death with red accents and death achievements.
| Model | Par Rate | Floor |
|---|---|---|
| 🏹 Haiku | $0.15 | $0.10 |
| ⚔️ Sonnet | $1.50 | $0.75 |
| ⚜️ Paladin | $4.50 | $2.00 |
| 🧙 Opus | $8.00 | $3.00 |
The floor prevents 1-prompt sessions from being instant BUST. The sqrt scaling means a 4-prompt Sonnet session has par $3.00, while a 16-prompt session has par $6.00 (not $24). Long sessions must be increasingly efficient to stay under par.
Rates and floors are configurable per model:
tokengolf config par # list all rates
tokengolf config par sonnet 1.5 # set Sonnet par rate to $1.50/prompt
tokengolf config par reset # restore defaults
tokengolf config floor opus 20.0 # set Opus floor to $20.00
tokengolf config floor reset # restore defaults| Class | Model | Difficulty | Feel |
|---|---|---|---|
| 🏹 Rogue | Haiku | Nightmare | Glass cannon. Prompt precisely or die. |
| ⚔️ Fighter | Sonnet | Standard | Balanced. The default run. |
| ⚜️ Paladin | Opus (plan mode) | Tactical | Strategic planner. Opus plans, Sonnet executes. |
| 🧙 Warlock | Opus | Casual | Powerful but expensive. |
Effort levels: Low / Medium / High / Max (Opus-only). Fast mode (/fast in Claude Code) is auto-detected and unlocks unique achievements (Lightning Run, Daredevil).
Efficiency (% of par used):
| 🌟 LEGENDARY | 🔥 EPIC | 💪 PRO | ✅ SOLID | 💥 BUST | |
|---|---|---|---|---|---|
| < 15% | < 30% | < 50% | < 75% | < 100% | > 100% |
Spend tier (model-calibrated — shown here for Sonnet):
| ✨ Mythic | 💎 Diamond | 🥇 Gold | 🥈 Silver | 🥉 Bronze | 💸 Reckless |
|---|---|---|---|---|---|
| < $0.10 | < $0.50 | < $1.50 | < $4.00 | < $10.00 | > $10.00 |
Thresholds scale per model — Haiku Diamond is $0.15, Opus Diamond is $2.50. Same relative difficulty, different absolute cost.
60+ achievements tracking how you prompt, what tools you use, and how efficiently you spend. Here are some highlights:
| Achievement | How | |
|---|---|---|
| 🥊 | One Shot | Completed in a single prompt |
| 🎯 | Sniper | Under 25% of par used |
| 💎 | Diamond | Haiku under $0.10 total |
| 🔪 | Surgeon | 1–3 Edit calls, under par |
| 🤫 | Silent Run | No extended thinking, SOLID or better |
| 👑 | Archmagus | Opus at max effort, completed |
| 🥷 | Ghost Run | Manual compact at ≤30% context |
| 🐺 | Lone Wolf | No subagents spawned |
| 🤦 | Hubris | Used ultrathink, busted anyway (death mark) |
| 💥 | Blowout | Spent 2× your par (death mark) |
Full achievement list (60+)
Class
- 💎 Diamond — Haiku under $0.10 total spend
- 🥇 Gold — Completed with Haiku
- 🥈 Silver — Completed with Sonnet
- 🥉 Bronze — Completed with Opus
- ⚜️ Paladin — Completed as Paladin (Opus plan mode)
- ♟️ Grand Strategist — EPIC efficiency as Paladin
Efficiency
- 🎯 Sniper — Under 25% of par used
- ⚡ Efficient — Under 50% of par used
- 🪙 Penny Pincher — Total spend under $0.10
- 💲 Cheap Shots — Under $0.01 per prompt (≥3 prompts)
- 🍷 Expensive Taste — Over $0.50 per prompt (≥3 prompts)
Prompting skill
- 🥊 One Shot — Completed in a single prompt
- 💬 Conversationalist — 20+ prompts in one run
- 🤐 Terse — ≤3 prompts, ≥10 tool calls
- 🪑 Backseat Driver — 15+ prompts but <1 tool call per prompt
- 🏗️ High Leverage — 5+ tool calls per prompt (≥2 prompts)
Tool mastery
- 👁️ Read Only — Won with no Edit or Write calls
- ✏️ Editor — 10+ Edit calls
- 🐚 Bash Warrior — 10+ Bash calls comprising ≥50% of tools
- 🔍 Scout — ≥60% of tool calls were Reads (≥5 total)
- 🔪 Surgeon — 1–3 Edit calls, completed under par
- 🧰 Toolbox — 5+ distinct tools used
Effort
- 🏎️ Speedrunner — Low effort, completed under par
- 🏋️ Tryhard — High/max effort, EPIC efficiency
- 👑 Archmagus — Opus at max effort, completed
Fast mode
- ⛈️ Lightning Run — Opus fast mode, completed under par
- 🎰 Daredevil — Opus fast mode, EPIC efficiency
Time
- ⏱️ Speedrun — Completed in under 5 minutes
- 🏃 Marathon — Session over 60 minutes
- 🫠 Endurance — Session over 3 hours
Ultrathink
- 🔮 Spell Cast — Used extended thinking during the run
- 🧮 Calculated Risk — Ultrathink + EPIC efficiency
- 🌀 Deep Thinker — 3+ ultrathink invocations, completed under par
- 🤫 Silent Run — No extended thinking, SOLID or better
- 🤦 Hubris — Used ultrathink, busted anyway (death mark)
Multi-model
- 🏹 Frugal — Haiku handled ≥50% of session cost
- 🎲 Rogue Run — Haiku handled ≥75% of session cost
- 🔷 Purist — Single model family throughout
- 🦎 Chameleon — Multiple model families used, under par
- 🔀 Tactical Switch — Exactly 1 model switch, under par
- 🔒 Committed — No switches, one model family
⚠️ Class Defection — Declared one class but cost skewed to another
Paladin planning ratio
- 🏛️ Architect — Opus handled >60% of cost (heavy planner)
- 💨 Blitz — Opus handled <25% of cost (light plan, fast execution)
- ⚖️ Equilibrium — Opus/Sonnet balanced at 40–60%
Rest & recovery
- 🔥 No Rest for the Wicked — Completed in one session
- 🏕️ Made Camp — Completed across multiple sessions
- 🧟 Came Back — Fainted (hit usage limits) and finished anyway
Context management (gear)
- 📦 Overencumbered — Context auto-compacted during run
- 🎒 Traveling Light — Manual compact at ≤50% context
- 🪶 Ultralight — Manual compact at ≤40% context
- 🥷 Ghost Run — Manual compact at ≤30% context
Tool reliability
- ✅ Clean Run — Zero failed tool calls (≥5 total)
- 🐂 Stubborn — 10+ failed tool calls, still won
Subagents
- 🐺 Lone Wolf — Completed with no subagents spawned
- 📡 Summoner — 5+ subagents spawned
- 🪖 Army of One — 10+ subagents, under 50% par used
Turn discipline
- 🤖 Agentic — 3+ Claude turns per user prompt
- 🐕 Obedient — Exactly one turn per prompt (≥3 prompts)
Death marks (fire on bust, not win)
- 💥 Blowout — Spent 2× your par
- 😭 So Close — Died within 10% of par
- 🔨 Tool Happy — Died with 30+ tool calls
- 🪦 Silent Death — Died with ≤2 prompts
- 🤡 Fumble — Died with 5+ failed tool calls
- 🎲 Indecisive — 3+ model switches
- 🍷 Expensive Taste — Over $0.50 per prompt
After install, a 3-line status bar appears in every Claude Code session showing efficiency rating, project info, cost, emotion, model, and context load.
██ 🌟 LEGENDARY 📂 myapp ⎇ main ✓
██ 😎 VIBING 💎 $0.42/9.90 ▓░░░░░░░░░░ 4%
██ ⚔️ Sonnet 🪶 ▓░░░░░░░░░ 8%
██ 💪 PRO 📂 api-server ⎇ feat/auth ●
██ 😤 GRINDING 🥉 $6.80/19.80 ▓▓▓▓░░░░░░░ 34%
██ ⚔️ Sonnet 📚 ▓▓▓░░░░░░░ 34%
Line 1: Efficiency rating + project name + git branch (✓ clean, ● dirty). Line 2: Emotion + cost vs par + progress bar. Line 3: Model class + context weight (🪶 · 📚 · 🎒 · 🧱 · 🪨 · 🗿 — feather to stone). Accent ██ color matches your efficiency tier. 💤 replaces the emotion icon when fainted.
Emotions are a composite signal: par %, context %, failed tools, prompt count. From 😎 VIBING through 😤 GRINDING to 🧟 ZOMBIE (past bust). Three display modes: tokengolf config emotions emoji (default), ascii (kaomoji + label on a 4th line), or off.
When you /exit, the scorecard appears automatically — cost vs par, model breakdown, achievements, tool usage.
██ 🏆 SESSION COMPLETE
██ ──────────────────────────────────────────────────
██ SPENT PAR USED MODEL TIER
██ $0.21 $1.50 14% ⚔️ Sonnet 🥇 Gold
██
██ 🌟 LEGENDARY
██ ──────────────────────────────────────────────────
██ Achievements unlocked:
██ 🎯 Sniper — Under 25% of par
██ 🥈 Silver — Completed with Sonnet
██ 🔥 No Rest for the Wicked — One session
██ ✅ Clean Run — Zero failed tool calls
██ 🧰 Toolbox — 5+ distinct tool types
██ 🤫 Silent Run — No extended thinking
██ ──────────────────────────────────────────────────
██ Model usage: 🏹 17% Haiku
██ Sonnet 83% $0.19 Haiku 17% $0.04
██ ──────────────────────────────────────────────────
██ Tool calls:
██ Read ×8 Edit ×4 Bash ×3 Grep ×2 Glob ×1
██ 💀 PAR BUST
██ ──────────────────────────────────────────────────
██ $48.00 /$22.14 par 217% ⚔️ Sonnet·High 💥 BUST
██ ──────────────────────────────────────────────────
██ 🤦 Hubris 💥 Blowout 🤡 Fumble 🔨 Tool Happy
██ ──────────────────────────────────────────────────
██ Cause of death: Par exceeded by $25.86
██ Tip: Use Read with line ranges instead of full file reads.
Ultrathink
Write ultrathink anywhere in your prompt to trigger extended thinking mode. It's not a slash command — just say it in natural language:
"ultrathink: is this the right architecture before I write anything?" "can you ultrathink through the tradeoffs here?"
Extended thinking tokens are billed at full output rate. A single ultrathink on Sonnet can cost $0.50–2.00 depending on problem depth. TokenGolf detects thinking blocks from your session transcripts and tracks invocations and estimated thinking tokens — both show on your scorecard.
The skill is knowing when to ultrathink. One expensive deep-think that prevents five wrong turns is efficient. Ultrathinking every prompt when you're at 80% of par is hubris.
The Meta Loop
Achievement names map directly to real session behaviors:
- Overencumbered = context bloat slowing you down
- Made Camp = hit usage limits, came back next session
- Ghost Run = surgical context management before the boss
- Hubris = reached for ultrathink on a tight par budget and paid for it
- Silent Run = solved it with pure prompting discipline, no extended thinking needed
- Lone Wolf = didn't spawn a single subagent; held the whole problem in one context
- Agentic = gave Claude the wheel and it ran with it — 3+ turns per prompt
These patterns compound over time. Better prompting habits → lower daily spend → better scores without even trying.
Why "TokenGolf"?
Code golf is the engineering practice of solving a problem in as few characters (or lines, or bytes) as possible. The constraint isn't the point — the discipline the constraint creates is the point. Writing the shortest possible solution forces you to understand the problem deeply and use your tools precisely.
Token golf is the same idea applied to AI sessions. Your budget is par. Every unnecessary prompt, every redundant context dump, every "can you also..." tacked onto a request is a stroke over par. The game doesn't literally resemble golf — it borrows the concept: optimize under constraint, measure your score, improve your game.
Hooks (9 total)
Installed automatically via plugin, or manually via tokengolf install (npm):
| Hook | When | What it does |
|---|---|---|
SessionStart |
Session opens | Auto-creates run, injects par budget into Claude's context. |
PostToolUse |
After every tool | Tracks tool usage by type. Fires par warning at 80%. |
PostToolUseFailure |
After a tool error | Increments failedToolCalls — powers Clean Run, Stubborn, Fumble. |
UserPromptSubmit |
Each prompt | Counts prompts. Injects halfway nudge at 50% of par. |
PreCompact |
Before compaction | Records manual vs auto compact + context % — powers gear achievements. |
SessionEnd |
Session closes | Scans transcripts for cost + ultrathink, saves run, displays scorecard. |
SubagentStart |
Subagent spawned | Increments subagentSpawns — powers Lone Wolf, Summoner, Army of One. |
Stop |
Claude finishes a turn | Increments turnCount — powers Agentic, Obedient. |
StatusLine |
Continuously | Live HUD with cost, tier, efficiency, context %, model class. |
State
All data lives in ~/.tokengolf/:
current-run-{cwd}.json— active run (per-project, so concurrent sessions in different repos don't collide)session-cost-{cwd}— cost sidecar from statusline (per-project)runs.json— completed run history (shared)config.json— user preferences (emotion mode, custom par rates)statusline.sh— stable copy of the HUD script (survives plugin/npm uninstall)
No database, no native deps, no compilation.