@mintapp/claude-quest

Interactive CLI onboarding quest for developers setting up Claude Code.

Quick Start

npx @mintapp/claude-quest

What It Does

The Mint Claude Quest is a gamified CLI experience that guides developers through:

1. The Prologue - Register your identity (GitHub user, team, OS, IDE)
2. The Arsenal - Install Claude CLI, Claude Desktop, IDE extension
3. The Guild - Install plugins from the Mint marketplace
4. The Connections - Set up MCP servers (GitHub, Atlassian, Figma)
5. The Spellbook - Learn skills, commands, agents, hooks, and parallel workflows
6. The Migration - Migrate from GitHub Copilot to Claude Code
7. The First Quest - Try the /ticket workflow, parallel sessions, and CLI tricks
8. The Report - Submit progress to the team dashboard

Features

• Cross-platform (macOS + Windows + Linux)
• Resume from any chapter (--chapter N)
• XP system with 6 levels and 8 badges
• Knowledge quizzes with bonus XP
• Multi-IDE support — select multiple IDEs (e.g. VS Code + Xcode) and install extensions for all of them
• Auto-execute commands — opens new terminal tabs for install commands (macOS iTerm2/Terminal, Windows cmd); clipboard fallback for Claude Code slash commands
• Parallel workflow training — teaches worktrees (claude -w), subagents (foreground/background), and Agent Teams with hands-on exercises
• Animated UI — rainbow title animation, typing effects, side-scrolling transitions between chapters, terminal beeps on badge unlocks
• Auto-detects existing tools (Claude CLI, Desktop, VS Code extensions)
• Reports setup status to the team dashboard (requires Mint VPN)
• Config-driven: all content lives in JSON files for easy updates

CLI Options

npx @mintapp/claude-quest                   Start or resume the quest
npx @mintapp/claude-quest --chapter 3       Jump to a specific chapter
npx @mintapp/claude-quest --reset           Reset all progress
npx @mintapp/claude-quest --help            Show help
npx @mintapp/claude-quest --version         Show version

Development

cd cli-onboarding
pnpm install
pnpm dev              # Run with tsx (no build needed)
pnpm typecheck        # TypeScript validation
pnpm build            # Compile to dist/
pnpm start            # Run compiled version

Configuration

All content is config-driven and lives in src/config/:

| File | Purpose | |---|---| | chapters.json | Chapter metadata (title, subtitle, XP, badge) | | quizzes.json | Quiz questions per chapter | | plugins.json | Plugin marketplace and team-specific plugins | | mcp-servers.json | Required and team-specific MCP servers | | badges.json | Badge definitions |

Architecture

cli-onboarding/
  bin/cli.ts              CLI entry point (arg parsing)
  src/
    index.ts              Main orchestrator (resume/new game flow)
    game/
      engine.ts           GameEngine class (XP, badges, persistence)
      platform.ts         Cross-platform detection helpers
      ui.ts               Terminal UI components (banners, animations, progress bars)
      quiz.ts             Quiz runner
      command-runner.ts   Auto-execute commands (new terminal tab / clipboard)
      transition.ts       Side-scrolling chapter transition animations
    chapters/
      0-prologue.ts       Identity registration
      1-arsenal.ts        Tool installation
      2-guild.ts          Plugin marketplace
      3-connections.ts    MCP server setup
      4-spellbook.ts      Advanced features education
      5-migration.ts      Copilot migration
      6-first-quest.ts    Hands-on practice
      7-report.ts         Dashboard submission
    content/
      ascii-art.ts        Logo, titles, chapter art
      lessons.ts          Knowledge scroll content
    api/
      dashboard.ts        Dashboard API client
    checks/
      claude-cli.ts       CLI detection
      claude-desktop.ts   Desktop app detection
      ide-extension.ts    IDE extension detection
    config/
      *.json              All configurable content

Dashboard API

The quest submits a report to POST /api/onboarding/complete (no auth required, VPN required).

Reports are stored in Cosmos DB onboarding container, partitioned by /user.

View all reports: GET /api/onboarding/complete (requires Basic Auth).

State Persistence

Progress is saved to ~/.claude-quest/progress.json via the conf package. Users can resume from any checkpoint.