⚔️ Claude RPG

Turn Claude Code into an RPG. Claude RPG is a Claude Code plugin with two halves that work together:

• The side-quest skill — hand any task to background subagent(s) with /side-quest <task>. Claude rates the task's Challenge Rating to pick the model, splits decomposable work across a party of parallel agents, and narrates the whole thing in Dungeons & Dragons style — always paired with a plain-English summary so the flavor never costs you information.
• The XP Counter — a live status line that tracks the D&D 5e XP you earn for completing quests (and everyday tasks), with levels, a to-next-level readout, a transient +XP ✨ flash after each award, and a 🎉 LEVEL UP animation.

Both halves share one persistent ledger at ~/.claude/side-quest/xp.json, so your XP is the same across every session and agent.

matt@laptop:~/git/claude-rpg  main  Opus 4.8
⚔️ Lv7 12,345 XP (655 to Lv8)          +700 XP ✨
ctx:42%  cache: 88% hit  30.1k read / 4.2k write
5h:12% (resets 3:45PM)  7d:34% (resets Mon 3:45PM)

Cross-platform

Runs on Windows, macOS, and Linux. Both scripts are pure Python 3 (stdlib only) — no jq, awk, bash, or platform-specific date required. The status line renders identically on every OS, and it's a single Python process per refresh instead of the ~30 shell forks the old bash version spawned every second.

Requirements: Python 3.8+ on your PATH (python3/python on POSIX, py/python on Windows). Git is optional — the status line shows the current branch when a repo is present.

Install

Option A — as a Claude Code plugin (recommended)

/plugin marketplace add https://git.trtmn.io/trtmn/claude-rpg
/plugin install side-quest@claude-rpg

Then run the one-time setup, which deploys the scripts, wires up the status line, and (with your approval) adds the ambient-XP rule:

launch the side-quest-setup agent

Restart Claude Code afterward so the status line takes effect.

Option B — manual install

1. Clone the repo:

   git clone https://git.trtmn.io/trtmn/claude-rpg.git
   

2. Copy the scripts to a stable location:

   macOS / Linux

   mkdir -p ~/.claude/side-quest
   cp claude-rpg/scripts/xp.py claude-rpg/scripts/statusline.py \
      claude-rpg/scripts/xp.sh claude-rpg/scripts/statusline.sh ~/.claude/side-quest/
   chmod +x ~/.claude/side-quest/*.py ~/.claude/side-quest/*.sh
   

   Windows (PowerShell)

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\side-quest" | Out-Null
   Copy-Item claude-rpg\scripts\xp.py,claude-rpg\scripts\statusline.py,`
             claude-rpg\scripts\xp.cmd,claude-rpg\scripts\statusline.cmd `
             "$env:USERPROFILE\.claude\side-quest\"
   

3. Add the status line and Stop hook to ~/.claude/settings.json (use the absolute path to the deployed script):

   macOS / Linux

   {
     "statusLine": {
       "type": "command",
       "command": "bash /Users/YOU/.claude/side-quest/statusline.sh",
       "refreshInterval": 1
     },
     "hooks": {
       "Stop": [
         { "hooks": [ { "type": "command", "command": "bash /Users/YOU/.claude/side-quest/xp.sh tick", "async": true, "timeout": 15 } ] }
       ]
     }
   }
   

   Windows

   {
     "statusLine": {
       "type": "command",
       "command": "python C:\\Users\\YOU\\.claude\\side-quest\\statusline.py",
       "refreshInterval": 1
     },
     "hooks": {
       "Stop": [
         { "hooks": [ { "type": "command", "command": "python C:\\Users\\YOU\\.claude\\side-quest\\xp.py tick", "async": true, "timeout": 15 } ] }
       ]
     }
   }
   

4. (Optional) Add the ambient-XP rule to ~/.claude/CLAUDE.md — see the block the side-quest-setup agent installs, or copy it from agents/side-quest-setup.md.

Usage

Run a side quest

/side-quest audit the repo for hard-coded secrets and write findings to secrets-audit.md

Claude rates the Challenge Rating, launches background agent(s) on the matching model, and reports back when they finish — with a loot report and the XP you earned.

Earn XP on ordinary tasks (ambient XP)

With the ambient-XP rule installed, Claude silently awards XP after any completed task, sized by difficulty. Nothing to do — just work, and watch the counter climb.

The XP ledger CLI

python3 ~/.claude/side-quest/xp.py status       # {"total_xp":…, "level":…, …}
python3 ~/.claude/side-quest/xp.py statusline    # ⚔️ Lv 7 · 12,345 XP
python3 ~/.claude/side-quest/xp.py award 3 success "manual quest"
python3 ~/.claude/side-quest/xp.py tick          # CR1 fallback if idle 120s

How XP and levels work

• XP per quest follows the D&D 5e Challenge Rating table: CR 1 = 200, CR 2 = 450, CR 3 = 700, CR 4 = 1,100, CR 5 = 1,800 … up to CR 10 = 5,900. success earns full XP, partial earns half, wipe earns zero.
• Levels follow a geometric curve — Level 2 at 1,000 XP, each subsequent step ×1.05, no level cap. The status line shows how much XP remains to the next level.
• The ledger (~/.claude/side-quest/xp.json) records total XP, level, quest count, and the last 100 quests. Writes are atomic, so concurrent sessions never corrupt it.

Uninstall

Remove the statusLine block and the side-quest Stop hook from ~/.claude/settings.json, delete the ## Ambient XP block from ~/.claude/CLAUDE.md, and delete ~/.claude/side-quest/. If you installed via the plugin marketplace, also run /plugin uninstall side-quest@claude-rpg.

License

MIT — see LICENSE.