@codewithdan/ai-repo-adventure-generator
Advanced tools
Generate beautiful HTML adventure websites from your codebase
Generate beautiful, interactive HTML adventure websites from your codebase! Transform your code repository into an engaging story-based exploration experience.
npm install -g @codewithdan/ai-repo-adventure-generator
Or use directly with npx:
npx @codewithdan/ai-repo-adventure-generator
Simply run the command in your project directory:
repo-adventure
This will guide you through:
repo-adventure [options]
Options:
--theme <theme> Theme: space, mythical, ancient, developer, custom, or all
--output <dir> Output directory (default: ./public)
--overwrite Overwrite existing files without prompting
--max-quests <num> Limit number of quests to generate (default: all)
--log-llm-output Save raw LLM output to tests/llm-output directory
--serve Start HTTP server and open browser after generation
--help, -h Show help message
Examples:
repo-adventure --theme space --output ./docs --overwrite
repo-adventure --theme all --output ./public --overwrite # Generate all themes
repo-adventure --theme mythical --max-quests 3 --serve # Limit quests and auto-serve
The generator requires LLM configuration to generate stories and adventure content.
Create a .env file in your project:
# OpenAI
LLM_API_KEY=your_openai_key_here
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o
# Azure AI foundry
LLM_API_KEY=<your_azure_key_here>
LLM_BASE_URL=https://<your_azure_ai_foundry_resource>.openai.azure.com
LLM_MODEL=gpt-4o
LLM_API_VERSION=2025-01-01-preview
# Or GitHub Models (free tier - very limited and can only be used with very small adventures)
GITHUB_TOKEN=your_github_token_here
LLM_BASE_URL=https://models.inference.ai.azure.com
LLM_MODEL=gpt-4o
# Or Local Ollama (results can vary and may not generate compatible output - you can try it! :-))
LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL=gemma3:27b
LLM_REQUEST_TIMEOUT=300000 # 5 minutes for slower local models
Create an adventure.config.json in your project root to guide quest generation. This file tells the AI which parts of your codebase are most important to explore.
{
"adventure": {
"name": "Your Project Name",
"description": "Brief description of what your project does",
"url": "https://github.com/yourusername/yourrepo",
"customInstructions": "[Optional: Any specific guidance for story generation]",
"quests": [
{
"title": "Core Features",
"description": "Explore the main functionality",
"files": [
{
"path": "src/main.ts",
"description": "Main entry point",
"highlights": [
{
"name": "initializeApp",
"description": "Application initialization"
}
]
}
]
}
]
}
}
The generator creates:
output-directory/
├── index.html # Main adventure page with story
├── quest-1.html # Individual quest pages
├── quest-2.html
├── quest-N.html # Dynamic number based on your codebase
├── summary.html # Adventure completion summary
└── assets/
├── theme.css # Combined theme + base + animations CSS
├── quest-navigator.js # Interactive navigation component
├── quest-navigator.css
├── compass-icon.svg
├── images/
│ └── (theme-specific images)
└── shared/
├── github-mark.svg # Dark GitHub logo
└── github-mark-white.svg # White GitHub logo
Use this prompt with any AI coding assistant to generate a custom adventure.config.json file for your project:
COPY AND PASTE THIS PROMPT:
Please analyze this codebase and create an adventure.config.json file at the root of the project to help users explore the project through guided quests.
Requirements:
- Identify 3-5 key areas of functionality in the codebase
- Select 2-4 representative files for each area
- Highlight 2-4 important functions/classes or other members per file
- Focus on entry points, main logic, and system integrations
Use this exact JSON structure:
{
"adventure": {
"name": "[Your Project Name]",
"description": "[Brief project description]",
"url": "https://github.com/[username]/[repo-name]",
"customInstructions": "[Optional: Any specific guidance for story generation]",
"quests": [
{
"title": "[Quest Name - e.g. 'Authentication System']",
"description": "[What users learn from exploring this area]",
"files": [
{
"path": "[relative/path/to/important/file.js]",
"description": "[Role of this file in the system]",
"highlights": [
{
"name": "[functionName or ClassName.method]",
"description": "[What this code does and why it matters]"
}
]
}
]
}
]
}
}
Prioritize files that contain:
✓ Main entry points (index.js, program.cs, main.ts, app.js, etc.)
✓ Core business logic and algorithms
✓ API routes and controllers
✓ Database models and data access
✓ Configuration and setup code
✓ Key middleware and utilities
Avoid:
✗ Test files, build scripts, or configuration-only files
✗ Simple utility functions without business logic
✗ Auto-generated or boilerplate code
Aim for 15-25 total highlights across all quests for the best exploration experience.
The generated file will enable:
When selecting "custom" theme, you'll be prompted to provide:
MIT
Dan Wahlin
FAQs
Generate beautiful HTML adventure websites from your codebase
The npm package @codewithdan/ai-repo-adventure-generator receives a total of 1,619 weekly downloads. As such, @codewithdan/ai-repo-adventure-generator popularity was classified as popular.
We found that @codewithdan/ai-repo-adventure-generator demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.