AI-powered Game Design Document generator
npm install gameforge-cli> Transform game ideas into production-ready Game Design Documents using AI
GameForge CLI is a terminal-based AI pipeline that turns raw game ideas into comprehensive, structured Game Design Documents (GDDs). It features an interactive interview process, strict validation, multi-agent generation, and outputs both JSON and Markdown documentation.
- š¤ AI-Powered Interview: Hybrid question system with smart defaults
- ā Disambiguation: Agents ask clarifying questions when needed
- š Structured Output: Valid JSON + readable Markdown
- š° Cost Tracking: Real-time budget monitoring and warnings
- š¾ Checkpoint System: Save and resume at any phase
- š Genre Templates: Quick-start templates for common game types
- ā
Validation: Consistency checking + adversarial gap analysis + interactive issue review
- šÆ Technical Specs: Math formulas, data structures, user stories
- šØ Multi-Agent System: Specialized agents for features, entities, creative, and technical specs
- š§ Modifier Agent: Edit existing GDDs with natural language requests
- Node.js 18+ installed
- Anthropic API key (get one here)
``bash`
npm install -g gameforge-cli
`bashClone the repository
git clone
cd GameForgeCLI
Edit the
.env file and add your Anthropic API key:`env
ANTHROPIC_API_KEY=sk-ant-xxxxx # Required: Your Anthropic API key
`Then build and link the CLI:
`bash
Build the project
npm run buildLink the CLI globally (makes 'gameforge' command available)
npm link
`$3
`bash
Check available commands
gameforge --helpList available templates
gameforge templates
`$3
For active development with auto-rebuilding:
`bash
npm run dev
`Note: When using
npm run dev, you'll need to run commands via node dist/index.js or keep npm link active after each rebuild.Quick Start
$3
`bash
Create a new GDD with standard budget
gameforge createUse quick budget (cheaper, less detail)
gameforge create --budget quickUse deep budget (more comprehensive)
gameforge create --budget deepStart from a template
gameforge create --template roguelike
`$3
| Tier | Cost Limit | Model | Description |
|------|-----------|-------|-------------|
|
quick | $2.00 | Haiku | Fast draft with minimal detail |
| standard | $10.00 | Sonnet 4.5 | Balanced quality and cost (recommended) |
| deep | $25.00 | Sonnet 4.5 | Maximum detail and depth |$3
-
roguelike - Procedural dungeons, permadeath, run-based progression
- farming-sim - Resource management, crop cycles, NPC relationships
- fps - Fast-paced combat, weapon variety, multiplayer
- soulslike - Stamina combat, difficult bosses, bonfire checkpoints
- metroidvania - Interconnected world, ability-gated progressionHow It Works
GameForge CLI follows a structured pipeline with user review gates:
$3
Interactive interview with 10 carefully designed questions. Features:
- Multiple choice with suggested answers
- ⨠AI Decide: Let the AI suggest smart defaults based on your answers
- āļø Custom Answer: Enter free-form text
- Real-time cost tracking$3
The Architect Agent transforms your answers into a validated GameBible JSON structure containing:
- Metadata (title, genre, scope, platforms)
- Features with technical specs, user stories, and dependencies
- Game objects (NPCs, items, monsters)
- Creative direction (art style, audio, assets)
- Technical requirements (engine, tools, localization)$3
Four specialist agents run in sequence to generate detailed Markdown docs:
1. Creative Specialist - Art style, asset lists, pipeline
2. Feature Specialist - Mermaid diagrams, math formulas, data structures
3. Entity Specialist - NPC/Item/Monster stat tables
4. Tech Specialist - Engine setup, tools, directory structure$3
Three-layer validation with interactive issue review:
1. Consistency Agent - Checks dependencies, naming conventions, circular refs
2. Chaos Agent - Adversarial critic finding gameplay gaps and scope issues
3. Interactive Issue Review - Review each issue one-by-one and select which to fix
4. Remediation Agent - Automatically fixes selected issues (up to 3 attempts per issue)At the review gate, you can:
- Review issues individually with context and descriptions
- Select which issues to fix and which to keep
- Run the Remediation Agent on selected issues only
- Export the final GDD with gap analysis showing any unfixable issues
$3
Throughout the pipeline, agents can ask clarifying questions when they encounter ambiguity. This ensures the final GDD accurately reflects your vision.
When Disambiguation Triggers:
- Architect: Vague scope, unclear monetization, minimal art direction
- Chaos: Critical issues with vague recommendations
- Feature Specialist: Features marked as "Very High" complexity
- Entity Specialist: Entity count exceeds reasonable scope
- Creative Specialist: Asset requirements seem unrealistic for scope
- Tech Specialist: Multi-platform targeting in early projects
Question Format:
Each disambiguation question provides:
1. 2 AI-generated suggestions - Context-aware options based on your game
2. ⨠AI Decide - Let AI choose with reasoning
3. āļø Custom Answer - Use your system editor for detailed input
Example:
`
ā The feature "Multiplayer Networking" is marked as "Very High" complexity.Select an option:
āŗ Keep it as-is and proceed
Simplify to peer-to-peer only
⨠AI Decide (Smart Default)
āļø Custom Answer
`The AI Decide option provides reasoning:
`
š¤ AI Suggests: Simplify to peer-to-peer only
Reasoning: For a Prototype scope, full client-server architecture
would significantly increase complexity. P2P is faster to implement.Accept this suggestion? (Y/n)
`$3
`
.gameforge/output//
āāā 00_Cover.md # Title page with concept
āāā Creative_Direction.md # Art, audio, assets
āāā Feature_Specifications.md # All features with diagrams
āāā Entity_Specifications.md # NPCs, items, monsters
āāā Technical_Specifications.md # Engine, tools, build
āāā 99_Gap_Analysis.md # Unfixable validation issues (if any)
āāā game_bible.json # Complete structured data
āāā Game_Design_Document.md # Combined GDD with table of contents
`Example Output
$3
`markdown
Weapon Crafting
Epic: EPIC-005: Core Crafting Loop
$3
Create long-term resource loops and player investment$3
`mermaid
sequenceDiagram
participant Step0 as Collect Resources
participant Step1 as Open Crafting Menu
participant Step2 as Select Recipe
participant Step3 as Confirm Craft
participant Step4 as Receive Item
`$3
Data Structure:
`cpp
struct CraftingRecipe {
List inputs;
Item output;
float craftTime;
int skillRequired;
}
`Math Formulas:
-
CraftTime = BaseTime (1.0 - SkillLevel 0.1)
- Variables: BaseTime (float), SkillLevel (int 0-10)File Location:
Source/Game/Crafting/
Complexity: High
`Configuration
$3
Create a
.env file in the project root:`env
ANTHROPIC_API_KEY=your_api_key_here
DEFAULT_MODEL=claude-sonnet-4-5-20250929
FALLBACK_MODEL=claude-haiku-4-5-20251001
MAX_BUDGET_USD=10.00
CHECKPOINT_DIR=.gameforge/checkpoints
OUTPUT_DIR=.gameforge/output
`Architecture
$3
`
src/
āāā agents/ # AI-powered agents
ā āāā base/ # BaseAgent with Anthropic SDK integration
ā āāā core/ # Inquisitor, Architect, Consistency, Chaos, Remediation
ā āāā specialists/ # Feature, Entity, Tech, Creative specialists
āāā config/ # Schemas, budgets, templates
ā āāā schema.ts # Zod schemas (Game Bible SSOT)
ā āāā budget.ts # Cost tiers and model pricing
ā āāā templates.ts # Genre templates
āāā core/ # Infrastructure
ā āāā StateMachine.ts # Phase flow control
ā āāā SessionManager.ts # Save/resume & session tracking
ā āāā Orchestrator.ts # Parallel specialist execution
āāā utils/ # Utilities
ā āāā costTracker.ts # Budget monitoring
ā āāā modelSelector.ts # Intelligent model selection
ā āāā fileManager.ts # File I/O
āāā index.ts # CLI entry point
`$3
1. Single Source of Truth: All data flows through the
GameBible schema
2. Multi-Agent System: Specialized agents for different domains
3. Progressive Enhancement: Start simple, AI fills in details
4. Validation Layers: Structural (Zod) + Logical (Consistency) + Design (Chaos)
5. Cost Awareness: Model selection based on complexity + budgetDevelopment
$3
`bash
npm run build
`$3
`bash
npm run dev
`$3
`bash
Run all tests (18 unit tests + integration tests)
npm testRun specific test suites
npm test tests/unit
npm test tests/integrationWatch mode
npm test -- --watch
`See tests/README.md for detailed testing documentation.
$3
`bash
npm run lint
`Advanced Usage
$3
`bash
List all saved sessions
gameforge sessionsView details for a specific session
gameforge session
`$3
`bash
Resume from the latest checkpoint of a session
gameforge resume Resume from a specific checkpoint
gameforge resume
`$3
`bash
Modify an existing Game Design Document
gameforge modify Enable debug logging
gameforge modify --debug
``The modify command allows you to make changes to previously generated GDDs using natural language. The Modifier agent will:
- Understand your requested changes
- Update the GameBible while preserving design intent
- Maintain ID naming conventions and dependency integrity
- Regenerate affected documentation sections
- PDF export not yet available (Markdown only)
- Limited to 10 discovery questions (can extend in code)
- English only (no i18n support)
- Requires stable internet connection for API calls
GameForge aims to be a complete Game Idea ā Production-Ready Tasks pipeline:
Contributions welcome! Please open an issue or PR.
MIT License - see LICENSE file for details
- Built with Anthropic Claude (Sonnet 4.5 & Haiku)
- Powered by Zod for schema validation
- CLI built with Commander and Enquirer
---
Made with ā¤ļø for game developers