tokengolf

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

Quick Start

Claude Code Plugin (recommended — auto-updates)

claude plugin marketplace add josheche/tokengolf
claude plugin install tokengolf@tokengolf

npm (alternative — requires hook setup)

npm install -g tokengolf
tokengolf install          # patches ~/.claude/settings.json

Homebrew

brew tap josheche/tokengolf
brew install tokengolf
tokengolf install

curl

curl -fsSL https://raw.githubusercontent.com/josheche/tokengolf/main/install.sh | bash

That's it. Open Claude Code, work normally, /exit — scorecard appears automatically.

npm users get auto-sync — hooks update automatically on version change.

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)

How It Works

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.

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

Character Classes