pokemon

A Claude Code mod that draws one pixel Pokémon at the right edge of the band above the prompt, reacting to what Claude is doing. It shows which tool Claude is using, drops a Poké Ball for each subagent, and levels up and evolves as you work. The mon, hearts, berries, bubbles, balls, and Zs are pixel art in one Raster. The meters are one-cell characters.

Pet it and feed it. Here Bulbasaur gets a pat and an oran berry.

Its bubble shows the tool Claude is running, a magnifier and then a pencil while Claude reads files and writes a haiku. The answered turn takes Pikachu to Lv 6.

Every subagent drops a Poké Ball, and the ball pops open when its subagent reports back.

Mons evolve at the levels from the games, or with a stone. Here Growlithe becomes Arcanine.

Every mon knows its moves from the games. Magikarp uses Splash, and nothing happens. Then Gengar uses Night Shade.

The sprites come from vscode-pokemon by Jakob Hoeg Mørk. This is an unofficial fan project, not affiliated with Nintendo or The Pokémon Company. See Credits and Disclaimer.

Requirements

• Claude Code v2.1.287 or later
• The terminal app. The Desktop app has no Raster, so the mod draws nothing there.
• A truecolor terminal (iTerm2, Ghostty, kitty, WezTerm). The band follows Claude Code's theme, so the bubble, the Zs, and the icons stay visible on light themes too.

Install

claude plugin marketplace add dgokcin/claude-pokemon-mod
claude plugin install pokemon@claude-pokemon

To hack on it, clone the repo and add the clone instead (claude plugin marketplace add ./claude-pokemon-mod). A local marketplace loads the mod in place, so edits apply on /reload-plugins.

Usage

Behavior

Some organizations run a policy plugin that keeps the settings hooks' events (classic.*) from reaching plugins you install yourself. Under one, the "!" still shows for questions, plan approval, and the idle minute, but not for permission dialogs.

Needs

Each mon has two meters at the bottom right of the band:

Each icon is 20%. The meters are stored with a timestamp, so they keep draining while Claude Code is closed. A new mon starts at 80%. The meters hide when the band is too narrow for them.

The meters also scale the XP a turn earns, from half when both are empty to one and a half when both are full. /pokemon needs turns needs off. The meters, the need bubbles, and the hungry and happy behavior then go away, and XP ignores the meters. Petting and feeding still play and still fill them.

Levels and evolution

Each turn of the main agent that ends with an answer earns 10 + 2 × level XP. A turn of two minutes or more earns double, and the meters scale it as above. Levels follow the medium fast curve from the games, where level L takes L³ XP. A new mon starts at the lowest level the games allow it, which is 5 or the level it evolves at, so Charmeleon starts at 16. With 30 s turns and well kept meters, a mon goes from 5 to 16 in about 75 turns and from 16 to 36 in about 400.

When a level-up reaches the mon's evolution level from Red and Blue, the evolution starts once the mon is idle. It glows, flickers between its two shapes faster and faster, and flashes into its new form. /pokemon stop cancels it, and the next level-up tries again. The level, XP, and meters carry over to the evolved mon.

The 19 mons that evolve with a stone or a trade, like Pikachu, Eevee, and Kadabra, evolve with /pokemon evolve. Eevee needs a pick, like /pokemon evolve jolteon.

The level shows above the meters as Lv 12, and in /pokemon.

Attacks

/pokemon attack picks a random move from the mon's moveset in hooks/moves.js and replies Pikachu used Thunderbolt!. /pokemon attack <move> picks one by name, ignoring case, spaces, and dashes. An unknown move lists the mon's moves, and so do /pokemon moves and /pokemon attack list. While a move plays, the mon stops walking and wakes up, and a second attack waits for it to end.

A move takes over the mon's body. A move aimed ahead turns the mon side on toward the roomier side of the strip and backs it up to the edge behind it, a column a tick, so the move plays across the whole strip, the framing every effect was tuned in. Then the mon winds up, lunges, recoils, or leaps as it hits. A move on itself, like Harden or Recover, plays where the mon stands and faces you, and the mon braces, shrinks, melts, glows, or falls asleep instead.

hooks/moves.js has two tables. MOVE_FX gives each move its effect, plus an optional color, a power of 1 or 2 for moves that share an effect at two sizes, and a text line printed after the announcement. MOVES lists each mon's moves by name. An entry can be { name, from: 'top' } to send a move out of the top of the sprite, as Vine Whip and the powders leave the Bulbasaur line's bulb, or { name, from: 'body' } to pour it from the whole body, as Koffing and Weezing do with Smog. An unknown effect plays impact.

The effects live in hooks/effects/, one file per family:

hooks/effects/draw.js holds the shared drawing helpers and lists what an effect can do to a frame. Teleport leaves the mon at a random spot, Dig tunnels it forward, Transform borrows another mon's sprite for a few seconds, and Splash does nothing at all.

To watch a move frame by frame without a terminal, render it to a PNG contact sheet:

node scripts/preview-attack.mjs pikachu thunderbolt          # from home, aiming left
node scripts/preview-attack.mjs pikachu thunderbolt --at 2   # from the left edge, aiming right

Mons

All 151 gen 1 Pokémon are included, plus the pikachu_female and venusaur_female variants. Names match the source folders, so use mrmime, farfetchd, nidoran_female, and nidoran_male. Each mon has a default and a shiny variant.

The source GIFs are 32x32. The build crops each mon to the smallest box that fits all its frames, so the band height depends on the cropped height. The band uses one row per two pixels, plus one row of headroom for the hop. Diglett is the smallest at 12 px (7 rows). Fearow, Gyarados, and Pidgeot are the tallest at 31 px (17 rows).

In fullscreen, Claude Code gives the band at most half the pane, minus the prompt and the status line, so a split pane can leave it only a few rows. When the mon doesn't fit, the band draws the scene at full size and then shrinks the whole strip to fit. Each shrunk pixel takes the most common color of the block it covers, and ties go to the darker color so outlines and eyes survive. Below 4 rows the band shows a line of text instead, like Pikachu Lv 12 ●●●●○ ❤❤❤❤♡. A pane that only changes height gets its new fit on the next redraw, within a minute.

Add a mon

1. Copy the four GIFs from media/gen<N>/<mon>/ in jakobhoeg/vscode-pokemon into sprites/<mon>/. The files are default_idle_8fps.gif, default_walk_8fps.gif, shiny_idle_8fps.gif, and shiny_walk_8fps.gif.
2. Run node scripts/build-frames.mjs.
3. Run /reload-plugins. The mod loads in place from the repo, so no version bump or reinstall is needed.

Layout

Development

node scripts/build-frames.mjs      # after changing sprites/
node scripts/preview-attack.mjs <mon> <move>   # writes /tmp/<mon>-<move>.png
node scripts/check-data.mjs        # moves, evolutions, and sprite frames agree
npx @biomejs/biome@2.5.15 ci .     # lint
claude plugin validate .
claude plugin test
claude --plugin-dir .              # live-reloading session

Each terminal cell holds two vertical pixels with ▀/▄ half blocks. The sprite paces inside a 40 column strip.

CI runs the lint, the table check, and claude plugin test on every pull request and push to main. Commits follow Conventional Commits. When a push to main passes and brings a feat, fix, or perf commit since the last release, CI opens a chore(release) pull request, or updates the one that's open. git-cliff picks the version (a feature bumps the minor version, a fix the patch), and the PR bumps plugin.json and CHANGELOG.md. Merging it tags the merge commit and publishes the GitHub release with git-cliff's notes. Docs, tests, and chores don't release on their own. Opening that PR needs "Allow GitHub Actions to create and approve pull requests" on, in the repository's Actions settings.

Credits

The sprites come from vscode-pokemon by Jakob Hoeg Mørk, the extension that puts Pokémon in your VS Code window. Those GIFs took slow, manual work to extract and make, and this mod would not exist without them. If you like the mod, give the original a star.

• sprites/ holds unmodified copies of the gen 1 GIFs from vscode-pokemon's media/ folder.
• hooks/frames.js holds the pixel frames that scripts/build-frames.mjs generates from those GIFs.
• vscode-pokemon builds on vscode-pets by Anthony Shaw.

Disclaimer

This is an unofficial, non-commercial fan project. It is not affiliated with, endorsed by, or sponsored by Nintendo, Creatures Inc., GAME FREAK inc., or The Pokémon Company.

Pokémon and Pokémon character names are trademarks of Nintendo. The sprite artwork is © Nintendo, Creatures Inc., GAME FREAK inc., and The Pokémon Company. Rights holders who want anything removed can open an issue.