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.
the idea isn't new, I borrowed it
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.
what it actually looks like
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.
missions are graded on real state, not vibes
Every mission is one of four tiers, and the grading gets less mechanical the
further you go:
-
Artifact, write or edit a file (a
CLAUDE.md, a config) and the engine checks the file itself. -
Invocation, actually run a
claudesession 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. -
Mastery, fix something that's conceptually broken (a skill whose
description doesn't say what its for, a subagent that won't fire), then
the engine runs a held-out test battery against your own
claudeCLI. - Judgment, write something graded on a rubric (a commit message, a skill description) and an isolated judge call scores it per criteria.
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.
try it
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.
where it's at, not all the levels exist yet
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.
Top comments (10)
Grading on real state instead of self-report is the part I like most here. In my own work I had case where a code comment was wrong, reviewer corrected it, and correction was also wrong, only running the thing showed the truth. So check.js approach feels right to me. For mission idea, maybe something around getting your session back after terminal died, this is where I lose most time in real usage.
Hey Artjoms, thanks for trying it out. That's a great suggestion. Recovering a session after the terminal dies is a real everyday pain. We should definitely have a mission that teaches about --continue or /resume commands. Naming sessions probably belongs in the same mission too
Feel free to open a PR or an issue if you want to take a crack at it or I'll try to get to it in the coming weeks!
Good, and one thought about how to grade it. If the mission only checks that --continue was run, it tests memory of a flag, not recovery. Harder check is that the session survives without the terminal, so something outside it must hold what you were doing, a note file or a named session you can find back later. I build a terminal multiplexer exactly because dying terminal is my normal weather, so this mission would be the one I actually need. I have prepared an example github.com/susheem-k/claude-quest/... on your project, you may check if it make sense
I had a look last night. This looks good! Have already merged it!
Thanks for merging it fast. One thing I noticed after, issue 14 about sandboxes being shared per mission and not per save touches the resume mission directly, because two saves on the same mission would share exactly the state that mission asks you to recover. So either sandbox gets scoped per save first, or the mission has to be written knowing state can be dirty from another character.
Yeah I have been meaning to separate the sandboxes and scope them to each game run / user. Will get to it.
I really like this idea, especially the way the missions are graded against real state instead of just trusting that the task was completed. The four grading tiers are a great part of the design too. Going from checking actual files and configuration, to verifying real invocations, held-out tests, and eventually rubric-based judgment feels much closer to how you would actually validate that someone understands something.
It also seems like a genuinely useful way to learn Claude Code. You are not just reading about a feature or answering a quiz about it, you actually have to use it correctly and leave something behind that can be verified. Very cool.
Thanks, that bit about not just reading but leaving something behind that can be verified is exactly what I was going for, glad it landed. If you end up playing it I'd genuinely love to hear where it breaks or feels off, still early days and a lot more of the campaign left to build. And if any mission ideas come to mind, PRs or even just comments are welcome.
Grading the filesystem instead of the chat is the part that actually teaches how these tools fail. Agents love to say "done" while CLAUDE.md is empty or the settings file never changed, and catching that with a real check is closer to daily use than any quiz. Curious whether the Judgment tier ends up teaching taste, or just teaching people to write for the judge prompt.
Thanks for your inputs @eduzsh ! Teaching about taste is something I haven't really thought about yet but its a great input. Right now, yeah the idea is to get people comfortable with changing skill descriptions to make it more tightly aligned with what the skill should be doing so that claude uses it. I think the mission about writing a skill by hand could have an advanced tier too where the skill's outcome is complex enough to make the learner really push hard on how to structure the skill description well. But honestly i think as long as you can explain what your skill needs to do exactly, and in fine detail, claude itself can write a pretty good skill description.