git-quest ⚔️

Turn your codebase into an RPG. An MCP server for GitHub Copilot CLI.

git-quest scans your repository for maintenance tasks — missing documentation, TODO comments, untested files — and presents them as RPG-style quests. Complete quests to earn XP, level up, and unlock badges!

Quick Start

# 1. Install & register as MCP server
npx git-quest setup

# 2. Open Copilot CLI in any project
copilot

# 3. Start questing!
> scan this repo for quests

Example Output

⚔️ QUEST BOARD — 5 quests found!
🌱 Level: Novice | XP: 0 [░░░░░░░░░░] 0% to Apprentice
──────────────────────────────────────────────────

[Quest #1] ★☆☆ 📜 "Scrolls of validateToken"
  → Add JSDoc documentation to `validateToken` in src/auth.ts
  → Reward: +10 XP
  → Hint: Add JSDoc documentation with @param and @returns tags

[Quest #2] ★★☆ 🔍 "The Forgotten Task: refactor to use proper error types"
  → TODO: refactor to use proper error types (src/utils.ts:1)
  → Reward: +15 XP
  → Hint: Implement the change described in the comment

[Quest #3] ★★★ 🐉 "The Untested Dragon: parser"
  → src/parser.ts has no corresponding test file
  → Reward: +25 XP
  → Hint: Create a test file with at least one test case

Features

🔍 Three Scanners

• Missing Docs (📜 ★☆☆) — Finds exported functions/classes without JSDoc
• TODO Hunter (🔍 ★★☆) — Finds TODO, FIXME, HACK, XXX comments
• Missing Tests (🐉 ★★★) — Finds source files without test files

📊 XP & Levels

Level	XP Required	Icon
Novice	0	🌱
Apprentice	25	⚔️
Journeyman	75	🛡️
Expert	150	🔮
Master	300	👑
Legend	500	🐉

🏅 Badges

Badge	Requirement
🩸 First Blood	Complete your first quest
📜 Scribe	Document 3 functions
🪲 Exterminator	Resolve 5 TODOs
🛡️ Guardian	Create 3 test files
🐉 Dragon Slayer	Complete a ★★★ quest
✨ Perfectionist	Complete all quests in a single scan

How It Works

1. Scan — git-quest walks your project files and runs scanners to find maintenance tasks
2. Accept — Choose a quest to work on; get detailed instructions and hints
3. Fix — Make the code improvement (add docs, resolve TODO, write tests)
4. Verify — git-quest re-scans to confirm the fix, awards XP and badges

Progress is saved in .git-quest.json in your project root. Commit it to share progress with your team!

Available Tools

Tool	Description
scan_quests	Scan repo for maintenance quests
accept_quest	Accept a quest by number
verify_quest	Verify quest completion
player_stats	Show level, XP, badges
quest_log	Show quest history

Demo

A demo-repo/ directory is included with intentionally flawed code that generates ~15 quests. Perfect for testing!

cd demo-repo
copilot
> scan this repo for quests

Contributing

Contributions welcome! Ideas for new scanners:

• Complexity analyzer (long functions)
• Dead code detector
• Dependency vulnerability scanner
• Code style enforcer

License

MIT