hamster

🐹 Hamster

Win rewards while your agent codes.

Hamster is a Claude Code plugin. While Claude works a long task, scan a QR code, install a rewarded game on your phone, and earn real USD as you hit in-game goals. /wallet shows what you've made — keep coding, your phone earns on the side.

Install

Claude Code

claude plugin marketplace add growlads/hamster-plugin
claude plugin install hamster@hamster

Restart Claude Code — that's the whole setup.

Codex

codex plugin marketplace add growlads/hamster-plugin
codex plugin add hamster@hamster

Restart Codex, then trust the hook: Codex shows "Hooks need review." Pick Review hooks (or Trust all and continue) and turn on Hamster's UserPromptSubmit hook — the QR can't run until it's trusted. (Codex gates every plugin hook this way.) On Codex, Hamster registers only the per-prompt QR nudge, not the SessionStart greeting — Codex fires SessionStart too late to be useful (see the launch banner below).

No token, API key, or config to set up — Hamster connects itself on first run (it mints and stores your per-user token automatically). When your next session starts, a QR card appears: scan it with your phone, install the game, and check /wallet for earnings.

Only requirement: Node.js ≥ 18 on your PATH (check with node --version). Without it nothing breaks — you just won't see the QR until Node is installed.

What you get

/wallet is namespaced as /hamster:wallet; you can also enable a bare /wallet — see bare commands.

Additional play surfaces (an on-demand /qr, a browser /hub, and a Mac iPhone-mirroring /play flow) are built but disabled in this release. The code lives under plugins/hamster/disabled/ — see its README to re-enable.

Codex extra (opt-in): Codex fires SessionStart on your first prompt, not at launch, so the welcome can't show the instant codex opens. An opt-in installer (scripts/codex-banner/) wraps the codex launcher to print the same welcome card at real launch — fully reversible. See the plugin README.

export HAMSTER_API_URL="http://localhost:8787"

(optional) bare commands

/wallet is namespaced (/hamster:wallet). To also get a bare /wallet:

bash plugins/hamster/scripts/install-bare-commands.sh   # then restart Claude Code

Requirements

Check Node with node --version. If it's missing, the nudge fails soft (it stays silent rather than disrupting your prompt) — install Node and retry.

🌍 Region note

Rewarded offers are served only in: US · CA · GB · DE · FR · IT · ES · AU.

The country that matters is where your phone is — it's checked at the phone's IP when you scan. If your phone is outside a supported region you'll land on a "Games Unavailable" page even though everything else is correct; a VPN on the phone set to a supported region resolves it. This is the single most common "why doesn't it work?" — it's geography, not a bug.

Troubleshooting

• QR scan says "Games Unavailable." Your phone is outside a supported region — see the region note. Turn on a VPN on the phone and rescan.
• No QR card appears. The nudge renders in Node and fails soft — install Node.js ≥ 18 and make sure node is on your PATH (it also mints your token automatically on first run).
• /wallet says it "couldn't connect automatically." Auto-connect needs Node.js ≥ 18 and a reachable backend — install Node and retry, or set HAMSTER_TOKEN in ~/.hamster/config yourself (see Install).

Repo layout