Most tool documentation teaches by just telling you things. You read a page about
/model
, or hooks, or subagents, nod along, and forget it by the time you'd
actually need it. I wanted something closer to how people actually learn a CLI,
by using it, with something checking whether you did the thing right or not.
So I built claude-quest, a text RPG that runs entirely inside a real
claude
session and teaches the Claude Code CLI zero to hero.
This is basically GameShell's philosophy
applied to Claude Code. GameShell teaches Unix shell commands by dropping you
into a real shell wrapped in a themed fake filesystem, and grading your
progress by checking real shell/filesystem state instead of asking you to self
report or answer a quiz question.
claude-quest
does the same thing, except the "filesystem" is a real Claude
Code environment. missions live in real sandbox directories, and progress is
checked by inspecting what you actually did, config files you wrote, hooks
that fired, tool calls that happened.
There's no separate app, no fancy terminal UI, none of that. You say "let's
play claude quest" inside a normal claude
session, and Claude itself becomes
the game master. It reads real output from the engine and narrates on top of
it, something like this:
> lets play claude quest
**The Gatehall**
You've just been let through the outer gate. The tower keeps no secrets
from those who bother to read the walls...
**Mission: First Contact** (Tier 1, Artifact)
Create a CLAUDE.md file in this sandbox recording how to run the
project's tests. Let me know when you're done and I'll check it.
> done
CLAUDE.md records how to run the tests. Claude Code will know next time.
MISSION_STATUS: complete
**What you actually learned:** Claude Code reads a file named CLAUDE.md
in your project root automatically, at the start of every session...
that's it, that's the whole interface. it's just a chat, with real commands
running underneath it and real files getting checked. nothing gets rendered,
nothing gets animated, it's plain text the way claude
sessions already look.
Every mission is one of four tiers, and the grading gets less mechanical the
further you go:
CLAUDE.md
, a config) and the engine
checks the file itself.claude
session and do the thing (switch
models, compact, check cost). the engine checks what landed afterward
(like .claude/settings.json
), never what you said in the session.claude
CLI.None of these ask you to type an answer into a prompt, they ask you to leave
a trace and then the engine checks the trace.
Inside any claude
session:
/plugin marketplace add susheem-k/claude-quest
/plugin install claude-quest@claude-quest
Then just say "let's play claude quest." Progress saves to ~/.claude-quest/
,
so it doesn't really matter which project your in when you pick it back up.
This is a playable alpha, not a finished game. The full loop already works
(characters, saves, hints, grading for all four tiers) but the campaign
doesn't cover everything Claude Code can do yet. Right now there's only a
handful of example missions, one or two per tier, across five arcs. More
missions are getting added.
And since this is open source, that part doesn't have to be just me. If
there's a Claude Code feature you wish more people knew how to use, a
command, a hook, a workflow you had to learn the hard way, I'd genuinely like to turn it into a mission. The mission format is just a directory with a goal, a hint, and a check.js
(the design doc has the exact file contract for it), so adding one doesn't require touching
the engine at all.
Open an issue with a
mission idea, or just send a PR with one built already, both are welcome.
if you try it and it teaches you something, a star on the repo genuinely
helps, it's how other people find it.