Bugdex

Bugdex draws your Claude Code session as a monster battle. When a test, lint, build or merge that Claude runs fails, a wild bug appears. A green run makes it faint and earns you XP, and if a test was written or fixed during the fight, the bug is caught for your Bugdex. Claude’s work does not change: Bugdex only watches, and it makes no model calls, so it costs zero tokens.

What it does

• The bug. Its species comes from the error text. There are 20, from Typhox for a TypeError and Importapus for a missing module to Conflux for a merge conflict. Its HP is the number of failures, and its level rises with them.
• Turns. Each later run of the same kind is a turn, and fewer failures is a hit. Tests, lint, builds and git conflicts each fight their own bug.
• Your creature. Patchling’s HP is the share of the context window still free. It evolves into Patchwarden at Lv16 and Patchtitan at Lv36.
• Winning and catching. A clean run of the same kind ends the fight with 30 XP, plus 15 per failure at the fight’s peak, plus 25 if the bug is caught. A catch needs a test file edited while the suite was still red. A green run after no fight earns nothing.
• Flakelings. Red, then green with no file edited, means a flaky test: 10 XP and a Flakeling entry.
• Confusion. One file edited three or more times with no progress on the next run makes your creature Confused: a hint that Claude is going in circles.
• Permission prompts. They show up as “A wild Bash appeared!”. It is only a picture: you still decide in Claude Code’s own dialog.

It draws a two-line band above the prompt, a battle pane that opens by itself when a bug appears, and a Bugdex pane with every species: in color if caught, a gray silhouette if only seen. The terminal gets half-block pixel art; the desktop app draws the same pixels as SVG. Level, XP and the Bugdex carry over between sessions.

For creatures that spawn from your prompts instead of failing tests, see cc-pokedex. Ahmet Sahin also wrote deutsch-loop, a German tutor above the prompt.

Install

Needs Claude Code 2.1.287 or later, plus a test, lint or build tool that Bugdex recognizes.

claude plugin marketplace add ahmtsahin/bugdex
claude plugin install bugdex@bugdex

The band appears above the prompt and the next failing run starts a fight. /bugdex opens your Bugdex, /bugdex battle the battle pane, and /bugdex band off or /bugdex band on hides or restores the band.

To try it on a planted bug, clone the repo, start claude --plugin-dir .. inside its bugdex-demo folder and ask Claude to run node --test, fix what fails and add a regression test.

How it works

Bugdex reads every Bash and PowerShell command Claude runs, with its output, after the tool finishes. The command decides the kind of fight; the output gives the failure count and the species. It recognizes the common test runners (Jest, Vitest, pytest, go test, cargo test and more), linters, type checkers, builds and git merge conflicts; the README’s Supported runners section has the full list. A run fails if it exits with an error or its output reports failures; one that fails without a count it can read is scored as one failure. Background and interrupted runs are ignored.

During a fight it also counts Edit and Write calls per file path, to spot confusion and catches. A file counts as a test if it sits in a folder such as tests/ or __tests__/, or is named like *.test.*, *.spec.*, test_*.py or *_test.go.

The tool.check hook runs after Claude Code’s own permission decision and only notes when it is to ask you, to draw the encounter. It returns the decision unchanged, so it cannot block or approve anything. tool.call hands every result back untouched, and prompt.submit only closes the battle pane without reading your prompt.

Your profile (XP, wins, and seen and caught counts per species) is saved in Claude Code’s plugin store under ~/.claude/plugins/store/. The current fight, including the paths of edited files, lives only in the session’s state. No command text or output goes into the store, and Bugdex makes no network requests.

Limitations

• It only sees commands Claude runs through its Bash or PowerShell tool. Tests you run yourself in another terminal, and runners not on the list, start no fight.
• In the terminal, the battle pane opens by itself only when the window is at least 144 columns wide. On a narrower one, press Battle on the band or run /bugdex battle.
• Progress lives on one machine. Syncing between machines is on the author’s roadmap, not in version 0.1.0.
• Nothing is drawn in claude -p or in the VS Code extension’s chat panel.