copilot-quest

🎮 Copilot Quest

An AI-Powered Text Adventure where GitHub Copilot CLI is Your Game Master

Every playthrough is unique. Every choice matters. Every world is invented on the fly by GitHub Copilot.

╔══════════════════════════════════════════════════════════╗
║   ██████╗  ██████╗ ██████╗ ██╗██╗      ██████╗ ████████╗║
║  ██╔════╝ ██╔═══██╗██╔══██╗██║██║     ██╔═══██╗╚══██╔══╝║
║  ██║      ██║   ██║██████╔╝██║██║     ██║   ██║   ██║   ║
║  ██║      ██║   ██║██╔═══╝ ██║██║     ██║   ██║   ██║   ║
║  ╚██████╗ ╚██████╔╝██║     ██║███████╗╚██████╔╝   ██║   ║
║   ╚═════╝  ╚═════╝ ╚═╝     ╚═╝╚══════╝ ╚═════╝   ╚═╝   ║
║                    Q U E S T                              ║
╚══════════════════════════════════════════════════════════╝

What is Copilot Quest?

Copilot Quest is a terminal-based text adventure game where GitHub Copilot CLI acts as the Game Master. Instead of pre-written stories, every scene, choice, character, and puzzle is dynamically generated by Copilot in real-time.

• 🎲 Random genres — Fantasy, sci-fi, cyberpunk, horror, steampunk... you never know what you'll get
• ⚔️ Dynamic combat — HP system with meaningful consequences
• 🎒 Inventory management — Collect and use items throughout your journey
• 🎨 ASCII art scenes — Each location comes with AI-generated terminal art
• ✍️ Free-form actions — Choose from suggestions OR type your own creative actions
• ♾️ Infinite replayability — No two playthroughs are ever the same

Prerequisites

• Node.js v22 or later
• GitHub Copilot CLI installed and authenticated

  npm install -g @github/copilot
  copilot
  /login
  

• A GitHub Copilot subscription (Pro, Pro+, Business, or Enterprise)

Installation

Quick Play (no install needed)

npx copilot-quest

Install Globally

npm install -g copilot-quest
copilot-quest

From Source

# Clone the repository
git clone https://github.com/YOUR_USERNAME/copilot-quest.git
cd copilot-quest

# Install dependencies
npm install

# Start the game!
npm start

How to Play

• Launch the game with npm start
• Enter your name — your adventurer identity
• Wait for Copilot to generate your unique world (takes ~10-15 seconds)
• Make choices using ↑↓ arrow keys and Enter
• Type custom actions by selecting "Type your own action..." option
• Survive — keep your HP above 0!
• Reach the finale — stories build toward a climax after ~15-20 turns

How It Works

┌─────────────┐     ┌───────────────────┐     ┌──────────────┐
│  Player      │────▶│  Copilot Quest    │────▶│ Copilot CLI  │
│  (Terminal)  │◀────│  (Ink/React TUI)  │◀────│ (AI Engine)  │
└─────────────┘     └───────────────────┘     └──────────────┘
  Arrow keys,         Game state mgmt,         Story generation,
  Enter, Text         UI rendering,            ASCII art,
  input               Prompt engineering        World building

The game uses Copilot CLI's programmatic mode (copilot -p "...") to send structured prompts containing the current game state. Copilot responds with JSON containing the narrative, choices, ASCII art, and game state changes. The app parses this and renders it as a beautiful terminal UI.

Tech Stack

• TypeScript — Type-safe game engine
• Ink — React for interactive CLIs
• GitHub Copilot CLI — AI game master (programmatic mode)
• Figlet — ASCII art title
• Chalk — Terminal colors and styling

Project Structure

copilot-quest/
├── src/
│   ├── index.tsx              # Entry point
│   ├── App.tsx                # Main game loop & state machine
│   ├── components/
│   │   ├── TitleScreen.tsx    # Splash screen with ASCII title
│   │   ├── NameInput.tsx      # Player name entry
│   │   ├── NarrativePanel.tsx # Story display with typing effect
│   │   ├── ChoiceMenu.tsx     # Choice selection + free-form input
│   │   ├── StatsBar.tsx       # HP bar, location, inventory
│   │   ├── LoadingScene.tsx   # Animated loading while Copilot thinks
│   │   └── GameOver.tsx       # Victory/defeat screen
│   ├── engine/
│   │   ├── copilot.ts         # Copilot CLI integration layer
│   │   ├── gameState.ts       # Game state management
│   │   ├── promptBuilder.ts   # Structured prompt engineering
│   │   └── parser.ts          # JSON response parsing with fallbacks
│   └── types/
│       └── game.ts            # TypeScript type definitions
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Built with ❤️ and GitHub Copilot CLI for the GitHub Copilot CLI Challenge