claudemon

Wild Pokemon appear while you work in Claude Code. Your prompts are steps through the grass: the longer the prompt, the further you walk, and the more chances something jumps out. So is the waiting — every twenty seconds Claude spends working is another step, because that is the half of the session you actually have free.

The walking happens while Claude does, not the moment you press enter: a prompt buys you the steps and the turn takes them, so anything that jumps out does it with the grass already moving.

One at a time, and only for half a minute: a Pokemon that appears while you are busy wanders off if you leave it there, so a long session never leaves a queue of battles waiting for you.

However many Claude tabs you keep open, they all walk one trainer through one patch of grass — see below.

The original 151. Fully local — no account, no backend, nothing about you leaving the machine.

Waiting, which is most of it. The walk only moves while Claude does, so you can tell from across the desk without reading anything.

And when something does jump out.

It lives in a terminal tab of its own, next to the one you work in. The status line in Claude tells you something is waiting; the game tab is where you go and fight it.

┌─ Terminal 1: claude ──────────────────────────────────┐
│ > refactor this component                             │
│ ███████░░░░░░░ 63% left | Opus 5                      │
│ ✦ A wild PIDGEY appeared!  ·  24s left  ·  claudemon  │
└───────────────────────────────────────────────────────┘

Install

Typed inside Claude Code. Nothing to clone.

/plugin marketplace add zamarrowski/claudemon
/plugin install claudemon@claudemon

That puts the plugin in place — the hooks that make Pokemon appear come from it.

Now restart Claude Code. Claude Code only picks up a plugin's commands and hooks at startup, so until you restart, the next line does not exist yet — if you type it straight after installing, nothing happens. Once you are back:

/claudemon-setup

This does the rest: the claudemon command, the status line, and the sprites. It prints a line per step and says so if one of them did not work.

Then two one-offs, which it reminds you of:

1. Restart Claude Code once more, so the new status line loads.
2. In a second terminal tab, run claudemon.

It asks for a name and a starter the first time, and after that it sits there waiting. Send a longish prompt in the Claude tab and watch the status line.

What you need first

[!WARNING] In macOS Terminal the sprites come out striped and stretched, and no setting fixes it. Use any of the other terminals above.

The 151 Pokemon ship with the plugin, so the only thing the install downloads is the sprites, which takes a few seconds. After that the only thing that ever goes out is the version check below, and nothing goes out at all with it switched off.

Updating

The version this is sits at the right-hand end of the home screen's bottom row. Once a day the game asks GitHub whether a newer one is out — a plain GET of the plugin manifest, about 300 bytes, sending nothing. If there is, the home screen says so:

◆ v0.7.0 is out · [u] update

u does it: it refreshes the marketplace, fetches the new version through claude plugin update, and reruns the installer to catch anything around the plugin that changed. Then two one-offs, which it tells you about — restart Claude Code so the new hooks and status line load, and relaunch claudemon, because a running process cannot swap its own code out.

Option says when that question gets asked. UPDATE DAILY is the default above. UPDATE LAUNCH asks every time claudemon starts instead — one request as the tab comes up, and none while you play, which is what you want if you leave a tab open for a week and would rather not wait a day to hear about a release. UPDATE OFF stops it entirely: nothing is offered and no socket is opened; the two commands under Coming from 0.5.0 below still work whenever you want them.

Updating through Claude Code instead is fine too. The claudemon command is kept pointing at whichever copy is newest — by a hook, because neither the command nor the status line can be rewritten by hand once they are on a PATH and in settings.json — so the game picks the new one up on its next start, and says ◆ v0.7.0 is installed until you restart it.

Coming from 0.5.0

0.5.0 has none of this in it, so it cannot tell you a new version is out: the first upgrade is the only one you do by hand. In a terminal — not at the Claude Code prompt, because /plugin has no update of its own; this lives in the CLI:

claude plugin marketplace update claudemon
claude plugin update claudemon@claudemon

The first line is not optional. Your copy of the marketplace is whatever it was when you added it, so without refreshing it the second line has nothing newer to find and tells you so.

Restart Claude Code, then run claudemon again. That is all of it — the version turns up in the bottom-right corner, and [u] does every upgrade after this one.

There is one thing 0.5.0 leaves behind that has to be undone, and it undoes itself. 0.5.0's installer wrote the directory it was installed from into both launchers and nothing ever revisited it; for a plugin install that path has 0.5.0 in it, so the command would go on starting 0.5.0 whatever else you installed — in silence, the only symptom being a game that never changes. The first prompt after the restart puts both right, and notes it in ~/.claudemon/claudemon.log. A clone is left alone, because a clone is meant to take precedence.

Uninstall

/plugin uninstall claudemon@claudemon

That stops the hooks. To also remove the command and put your status line back, run the installer's undo — from the plugin copy, before you uninstall it:

node "$CLAUDE_PLUGIN_ROOT/tools/install.mjs" --uninstall

Your save is left alone either way — delete ~/.claudemon/ as well to be rid of it.

From a clone instead

For hacking on it, a clone works the same way and takes precedence over the installed copy:

git clone https://github.com/zamarrowski/claudemon
cd claudemon
node tools/install.mjs

That does everything the steps above do, including installing the plugin from the clone — so it needs no slash commands and only one restart, at the end. Keep the directory where it is: the launcher prefers it while it exists.

Two checks, one floor — the 20.19 above, which is what engines says and what the oldest leg of CI runs. npm ci && npm test puts the suite through Vitest; npm ci && npm run lint brings in the linter, which has opinions about correctness and none about how the code looks. The game still has no runtime dependencies — everything installed is a tool. The odd .19 is the floor those tools share, and the two are one number on purpose.

Installing also points git at .githooks, so a commit runs those checks before it is written: the linter, Prettier, and one Vitest pass that is the suite and the coverage floor at once — five seconds, near enough. It reads the working tree rather than the index, so a half-staged change is checked as whatever is on disk, and git commit --no-verify skips the lot when that is what you want.

CONTRIBUTING.md has the rest of it: the sprites the tests need, previewing a screen without playing to it, and what a pull request is expected to carry.

Controls

Arrow keys move, enter confirms, esc goes back, q quits. Any key advances a battle message. That is the whole scheme — it is the same everywhere.