⏳ Cooldown

MCP server for Claude Code that launches a game when you hit your usage limit, with a countdown until your tokens come back. Wait patiently. Smash bricks.

Play now: https://amudotcom-byte.github.io/cooldown/ (works on phones too)

How it works

Claude Code keeps MCP servers alive for the whole session — so even when the model itself is rate-limited, Cooldown keeps running:

1. A watcher thread tails ~/.claude/projects/**/*.jsonl every 15s.
2. When Claude Code hits the usage limit, it writes an API-error entry containing limit reached (usually with the reset epoch, e.g. ...limit reached|1751500800).
3. Cooldown opens the game with a countdown to reset. When it hits zero: YOU'RE BACK — return to Claude Code.

It picks the right version for how you run Claude Code (MCP servers inherit its env):

you run Claude Code from	it opens
desktop app (CLAUDE_CODE_ENTRYPOINT=claude-desktop)	hosted game in your browser (localhost fallback when offline)
terminal CLI (TERM/TERM_PROGRAM present)	ASCII game in a new iTerm/Terminal window (tui.py)
claude.ai in a browser	local MCPs don't run there — bookmark the hosted URL

Override with COOLDOWN_UI=browser|terminal, or per-call via the ui arg of start_game.

Detection only trusts entries with isApiErrorMessage: true, so a conversation merely talking about limits can't trigger it. A state file (~/.cache/cooldown/last_trigger) dedupes so multiple sessions don't each open a tab.

Install

git clone https://github.com/amudotcom-byte/cooldown ~/cooldown
claude mcp add --scope user cooldown -- python3 ~/cooldown/server.py

Pure Python stdlib, no dependencies. macOS for now (uses open/osascript to launch the game).

Let your agent install it

Paste this into Claude Code (or any agent with shell access):

Install the Cooldown MCP: clone https://github.com/amudotcom-byte/cooldown to ~/cooldown, then run claude mcp add --scope user cooldown -- python3 ~/cooldown/server.py. It needs no dependencies. It watches for Claude usage-limit events and opens a game with a countdown until my usage resets.

Restart your session afterwards and the usage_status / start_game tools are available.

Tools

tool	what it does
usage_status	approximate token usage over the last 5h across all projects + last limit event
start_game	open the game now (optional reset_epoch for the countdown)

Try: "what's my usage looking like?" or "start the cooldown game".

Game

Breakout: mouse / arrow keys / touch, click or space to launch. 5 rows of bricks, 3 lives, each cleared level speeds the ball up. Best score persists in localStorage. Pauses automatically when the tab is hidden.

Add your game

Built a browser game? Get it in front of every rate-limited dev in the cooldown arcade — with a link back to your site. Free while we're small.

1. Fork this repo
2. Add your game to games.json:

   { "name": "Your Game", "desc": "one line about it", "url": "https://yourgame.com", "author": "you" }

3. Open a PR

Rules: playable in a browser, no login wall to start playing, family-friendly, loads fast. Featured placement (top slot) will be a paid option later — early submitters get grandfathered goodwill.

Terminal version

ASCII Breakout for playing right in the terminal while you wait:

python3 ~/cooldown/tui.py                # auto-detects reset time from transcripts
python3 ~/cooldown/tui.py --reset EPOCH  # explicit countdown
python3 ~/cooldown/tui.py --snapshot 300 # print one text frame (no curses), for demos/tests

← → or a/d move · space launch · r restart · q quit. Same rules as the browser game.

Env overrides (testing)

• COOLDOWN_PORT — game port (default 4517)
• COOLDOWN_PROJECTS_DIR — transcript dir to watch
• COOLDOWN_NO_BROWSER=1 — log instead of opening the browser
• COOLDOWN_POLL_SECS — watcher interval