Gamified, story-driven CLI trainer — learn by doing, in your real terminal or your browser.

What is this?

Terminal Tutor replaces sprawling docs and copy-paste tutorials with quests — short, narrative missions where every beat of the story maps to a real command you run in your shell (or in the browser). It watches what you run, verifies it worked, and unlocks the next beat.

---

Features

The web version runs entirely in your browser. No install, no setup. Looks and feels exactly like a real terminal.

👉 terminal-tutor.vercel.app

Features:

• xterm.js terminal emulator — real keyboard input, cursor, scrollback
• Simulated shell responds to ls, cd, cat, git, gh, npm, and more
• Saves progress to localStorage — quit any time, resume later

---

Tech Stack

• Language: TypeScript
• CLI: Node.js with custom game engine
• Web: Next.js 14 (App Router) + xterm.js terminal emulator
• Storage: localStorage for progress persistence

---

Setup

Browser Version (Recommended)

👉 terminal-tutor.vercel.app

No installation required — just open and play!

Local CLI Version

# Requires Node 18+
git clone https://github.com/carlosfranzetti/terminal-tutor.git
cd terminal-tutor
npm install
node bin/tt.js

Or install globally:

gnpm link
# Now run 'tt' from anywhere
tt

---

Quest packs

Pack	Tool	Stories	Steps	Total XP
Ghost in the Shell	gh copilot	3	25	~430

Ghost in the Shell — gh copilot

Three branching stories about using gh copilot explain and gh copilot suggest when you're stuck in the terminal.

Story	Setting
Summon the Copilot	Standup in 20 minutes. Learn gh copilot before the sprint starts.
Debug at 3am	Production down. Cryptic error. Stack Overflow has nothing. You have Copilot.
The New Hire's Secret Weapon	Week 1. Impossible ticket. gh copilot suggest writes the commands you don't know yet.

Each story has a branching decision point — your choice shapes the path through the quest.

---

Screenshots

---

Controls

Key	Action
Enter	Run the command
h	Request a hint (−25% XP penalty)
s	Skip current step (no XP)
q	Quit and save progress

---

Adding a quest pack

A pack is a single .js file in quests/. Drop it in and it auto-loads at next launch.

Simple pack (flat steps)

// quests/my-pack.js
export default {
  id: 'my-pack',
  title: 'The Pack Title',
  synopsis: 'One-line pitch.',
  tool: 'my-cli',
  stories: [
    {
      id: 'story-1',
      title: 'Story One',
      setting: 'One-liner shown in the story picker.',
      steps: [
        {
          id: 'step-1',
          narration: 'The story beat — second person, present tense.',
          objective: 'What the player must do.',
          verify: { mode: 'shell', stdoutContains: 'expected output', exitCode: 0 },
          hints: ['Vague hint', 'More specific', 'Nearly explicit — try: `command`'],
          xp: 30,
        },
      ],
    },
  ],
};

With branching

steps: [
  {
    id: 'bp-1',
    type: 'branch',
    narration: 'Two paths appear before you.',
    branches: [
      {
        label: 'Path A',
        flavor: 'One-line description shown in picker.',
        steps: [/* normal steps */],
      },
      {
        label: 'Path B',
        flavor: 'Alternative route.',
        steps: [/* normal steps */],
      },
    ],
  },
],

Verification modes

Mode	What it checks
shell	Runs the command; evaluates exitCode, stdoutContains, stdoutMatches (regex), stderrContains, custom(result, input)
which	Checks a binary is on PATH (verify.binary)
prompt	Multiple-choice question (verify.choices, verify.answer or verify.answers[])

See CONTRIBUTING.md for the full authoring guide.

---

Web app (browser version)

The web version lives in web/ — a Next.js 14 app with App Router and TypeScript.

web/
  app/              Next.js app router
  components/
    TerminalGame.tsx  xterm.js terminal + full game loop
  lib/
    quests/         Quest pack definitions (TypeScript mirrors of quests/)
    shell-sim.ts    Simulated shell (ls, git, gh, npm, …)
    verifier.ts     Predicate evaluation (same logic as CLI verifier.js)
    xp.ts           XP / level math
    hints.ts        Hint ladder + XP penalty
    progress.ts     localStorage progress store
    types.ts        Shared TypeScript types

Develop the web version

cd web
npm install
npm run dev     # http://localhost:3000
npm run build   # production build

Deploy to Vercel

cd web
npx vercel --prod

---

Project layout

bin/tt.js          CLI entrypoint
src/app.js         CLI screens and flow
src/engine/        loader, runner, verifier, hints, progress, xp
src/ui/            theme, splash, browser, player, components
quests/            CLI quest packs (.js)
web/               Browser version (Next.js 14, TypeScript)
test/              Unit and integration tests
CLAUDE.md          Repo guide for AI assistants
TDD.md             Full technical design document
CONTRIBUTING.md    How to add quest packs and contribute code

---

Contributing

Contributions are welcome — bug fixes, new quest packs, and web improvements all appreciated.

The highest-leverage contribution is a new quest pack. A single well-written pack can teach an entire CLI tool to someone who's never touched it. See the Adding a quest pack section above for the format.

How to contribute

1. Fork the repo and create a branch (git checkout -b feat/my-quest)
2. Make your changes — quest packs go in quests/, web mirrors in web/lib/quests/
3. Run the tests — all 27 must be green before you open a PR:

   npm test

4. Play through your changes — launch node bin/tt.js and complete the quest end-to-end
5. Open a pull request with a short description of what the pack teaches and why it fits

Guidelines

• Quest narration is written in second person, present tense ("You stand at the gates...")
• Hints follow a three-tier ladder: vague concept → direction → near-explicit command
• Verification should be lenient — prefer stdoutContains and regex over exact matches
• Keep quest packs under 200 lines; split into multiple stories if the scope grows
• Every new quest pack must have an order field so it sorts correctly in the menu

Reporting bugs

Open a GitHub issue with:

• What you ran and what you expected
• What actually happened (paste the terminal output)
• Your OS and Node.js version (node --version)

License

MIT — Carlos Franzetti