claude-mario-runner

A Chrome-dino-style infinite runner that lives in your terminal. Claude Code themed — dodge bugs, merge conflicts, walls, exceptions, and drones.

🏆 Leaderboard: https://claude-mario-runner.vercel.app  ·  📦 npm: https://www.npmjs.com/package/claude-mario-runner  ·  📝 Blog: I built and shipped a game this weekend (mirror)

score 0                              tier easy                           best  0

                                                                  ████████
                                                                  #o####o#
                                                                  ########
                                                                  # #  # #
──────────────────────────────────────────────────────────────────────────

Install & run

Requires Node.js ≥ 20.

Play instantly (no install)

npx claude-mario-runner

Install globally

npm install -g claude-mario-runner
claude-mario

From source

git clone https://github.com/TejasAmle/claude-mario-runner.git
cd claude-mario-runner
npm install
npm run build
npm start

Or during development (no build step):

npm run dev

Global leaderboard

Live at claude-mario-runner.vercel.app — top scores across the world, light/dark toggle, retro pixel cursor, background chiptune.

Every new personal best auto-submits to the public board. The first time you play, you'll be prompted for a handle (2–24 chars, lowercase letters/digits/dash). Leave it blank to play offline — nothing is submitted.

claude-mario login <handle>    # set a handle locally
claude-mario login             # sign in with GitHub (gets a ✓ verified badge)
claude-mario whoami            # show current handle + identity
claude-mario leaderboard       # print the current top scores
claude-mario submit-disable    # opt out of submissions
claude-mario logout            # clear local profile

If the network is down when you hit a new best, the submit is parked in a local queue (~/.claude-mario-runner/submit-queue.jsonl) and retried the next time you launch the game.

The profile lives at ~/.claude-mario-runner/profile.json (mode 0600). A GitHub access token is only stored there after login (scope: read:user).

Controls

Key	Action
Space / ↑ / W	Jump
↓ / S	Crouch (hold)
Enter	Start / retry
Q / Esc	Quit

Obstacles

Kind	Glyph	Size	Clear by	Appears in
bug	██	2×1	Jump	Easy+
conflict	▓▓▓	3×2	Jump	Easy+
wall	██	2×3	Jump	Medium+
exception	▒▒▒	3×3	Jump	Hard+
drone	◆	4×10	Crouch	Medium+

Drones are aerial — they hover right through the full jump arc, so jumping won't save you. You have to duck.

Difficulty tiers

Tier	Starts at	Speed	Min gap	Max gap	Aerial prob	Adds
easy	0 s	22	30	46	0%	bug, conflict
medium	30 s	26	22	34	18%	+ wall, drone
hard	75 s	38	16	26	25%	+ exception
insane	120 s	52	12	20	32%	all

Speed eases smoothly between tiers — no teleport at boundaries.

Jump physics

Tuned to feel like Chrome's T-Rex dino, with a bias toward longer horizontal glide:

• Peak height ≈ 10 cells (~2.5× mascot height)
• Airtime ≈ 0.83 s
• Horizontal reach at easy speed ≈ 18 cells
• Collision hitbox is 6 wide; visual sprite is 8 wide (the # # # # leg-gap row is visual only, same trick Chrome dino uses)

While airborne, the mascot is above every ground obstacle — multiple can pass safely under a single jump. Only the drone extends into the jump arc.

Development

npm run dev         # run with tsx, no build
npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm test            # vitest run
npm run test:watch  # vitest
npm run build       # tsup → dist/
npm run format      # prettier --write

Clearability simulation

scripts/clearability-sim.ts sweeps every obstacle at every tier speed across every reasonable jump-timing, and reports whether it's jumpable / crouchable / survivable-while-standing. Used to verify the jump tuning whenever physics change.

npx tsx scripts/clearability-sim.ts

Reproducible runs

Pass a seed to get a deterministic obstacle sequence (useful for debugging):

npm start -- --seed 42

Architecture

src/
├── engine/        # renderer, input, main loop, terminal alt-screen
├── game/          # physics, runner, obstacles, world (tiers + spawning), score
├── assets/        # sprite/glyph definitions
├── net/           # leaderboard submit, offline queue, GH device-flow, profile
├── app.ts         # state machine: title → playing → gameover
├── cli.ts         # subcommand dispatch (login, whoami, leaderboard, …)
└── index.ts       # entry point

web/               # Next.js app deployed to Vercel — API + leaderboard page
├── app/           # / (leaderboard UI) + /api/submit + /api/leaderboard
└── lib/           # Redis keys, rate limits, validation, types

• Fixed 30 Hz timestep for deterministic physics across terminals
• Seeded PRNG (mulberry32) for reproducible obstacle sequences
• AABB collisions — hitbox smaller than sprite for forgiving play
• Time-based tiering on elapsedSec, not distance, so difficulty ramps at real-world seconds regardless of terminal width

License

MIT © Tejas Amle