⛳Why "TokenGolf"?

Code golf is the engineering practice of solving a problem in as few characters as possible. The constraint isn't the point — the discipline the constraint creates is the point. Writing the shortest 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.

🎮Two Modes

Flow Mode

Passive tracking, zero friction

Just work normally. TokenGolf runs in the background via Claude Code hooks.

Auto-starts on every Claude Code session
Scorecard appears on /exit
No pre-configuration required
Perfect when you're in a flow state

Roguelike Mode

Pre-commit. Stakes. Permadeath.

Declare your quest, pick a budget, choose your class. Bust the budget = the run dies.

5-floor structure (Write → Test → Fix → Review → PR)
Budget bust = permadeath, logged as a death
Trains deliberate, efficient prompting
Roguelike practice makes Flow sessions better

📸In Action

Live HUD — appears in every Claude Code session. Shows quest, cost, efficiency rating, context pressure, and model class. Run tokengolf demo to preview all states.

Auto Scorecard — appears on /exit. Real scorecard from building TokenGolf itself: $40 flow session, 27 ultrathink invocations, Class Defection for declaring Sonnet but spending 89% on Opus.

⚔️Character Classes

Class	Model	Difficulty	Feel
🏹 Rogue	claude-haiku-4-5	Hard	Glass cannon. Must prompt precisely.
⚔️ Fighter	claude-sonnet-4-6	Normal	Balanced. The default run.
🧙 Warlock	claude-opus-4-6	Easy	Powerful but expensive.

💰Budget Tiers

💎

Diamond

under $0.10

🥇

Gold

under $0.30

🥈

Silver

under $1.00

🥉

Bronze

under $3.00

💸

Reckless

over $3.00

🔄The Meta Loop

The dungeon crawl framing maps directly to real session behaviors. These aren't just flavor — they're patterns you already have, named so you can recognize and improve them.

📦 Overencumbered

Context bloat slowing you down. The model is carrying too much history to reason cleanly.

🏕️ Made Camp

Hit usage limits mid-run. Came back next session and kept going.

🥷 Ghost Run

Surgical context management. You compacted at 30% and still had plenty of room for the boss.

🤦 Hubris

Reached for ultrathink on a tight budget and paid for it. The spell didn't save you.

🤫 Silent Run

Solved it with pure prompting discipline. No extended thinking needed.

🐺 Lone Wolf

No subagents. You held the whole problem in one context and saw it through.

Roguelike mode surfaces these patterns with stakes. Flow mode lets them compound over time. Roguelike practice makes Flow sessions better. Better Flow = lower daily spend = better scores without even trying.

🏆Achievements

Class

💎

Diamond

Haiku run under $0.10

🥇

Gold

Completed with Haiku

🥈

Silver

Completed with Sonnet

🥉

Bronze

Completed with Opus

Efficiency

🎯

Sniper

Under 25% of budget used

⚡

Efficient

Under 50% of budget used

🪙

Penny Pincher

Total spend under $0.10

💲

Cheap Shots

Under $0.01 per prompt (≥3 prompts)

🍷

Expensive Taste

Over $0.50 per prompt — won or died

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, less than 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 in one run

🐚

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 budget

🧰

Toolbox

5+ distinct tools used in one run

Time

⏱️

Speedrun

Completed in under 5 minutes

🏃

Marathon

Session over 60 minutes

🫠

Endurance

Session over 3 hours

Extended Thinking

🔮

Spell Cast

Used extended thinking in a won run

🧮

Calculated Risk

Extended thinking + LEGENDARY efficiency

🌀

Deep Thinker

3+ thinking invocations, completed under budget

🤫

Silent Run

No extended thinking, SOLID or better

Multi-Model

🏹

Frugal

Haiku handled ≥50% of session cost

🎲

Rogue Run

Haiku handled ≥75% of session cost

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

📦

Overencumbered

Context auto-compacted during a won 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 tool calls total)

🐂

Stubborn

10+ failed tool calls and still won

Subagents

🐺

Lone Wolf

Completed with no subagents spawned

📡

Summoner

5+ subagents spawned in one run

🪖

Army of One

10+ subagents spawned, under 50% budget used

Turn Discipline

🤖

Agentic

3+ Claude turns per user prompt

🐕

Obedient

Exactly one turn per prompt (≥3 prompts)

Death Marks

🤦

Hubris

Used extended thinking, busted anyway

💥

Blowout

Spent 2× your committed budget

😭

So Close

Died within 10% of budget

🔨

Tool Happy

Died with 30+ tool calls

🪦

Silent Death

Died with ≤2 prompts

🤡

Fumble

Died with 5+ failed tool calls

⌨️CLI Commands

terminal

# Install
$ npm install -g tokengolf
$ tokengolf install          # patches ~/.claude/settings.json with hooks

# Roguelike — declare before you start
$ tokengolf start            # quest wizard: model + budget
$ tokengolf status           # live run state
$ tokengolf win              # complete run, show scorecard
$ tokengolf bust             # permadeath — budget busted

# Flow — just /exit Claude Code, scorecard auto-appears
$ tokengolf scorecard        # show last run's results
$ tokengolf stats            # career dashboard