FAQ

• Visual task management Kanban
• 8+ AI coding agent integrations (Claude, Cursor, Gemini, etc.)
• Git worktree isolation for safe experimentation
• Multiple attempts per task (try different agents)
• MCP server for AI agent integration
• 100% open source and self-hostable

• Chat with AI, get code, ship it
• Lost in chat history
• Code breaks in 2 weeks
• No experimentation or comparison
• Vendor lock-in to one AI

• You plan tasks in persistent Kanban
• AI agents execute in isolated worktrees
• Compare multiple agent approaches
• Review and understand before merge
• Code stays maintainable
• No vendor lock-in (8+ agents supported)

• No subscription fees
• No usage limits
• Self-hostable on your machine
• No vendor lock-in
• Community-driven development

• AI agent API costs (Claude, Gemini, etc.) - BYOL (Bring Your Own LLM)
• Or use free/open-source agents (OpenCode, Qwen Code)

• Claude Code (Anthropic) - Best for complex logic, security
• Cursor CLI - Modern React patterns, frontend
• Gemini (Google) - Fast iterations, good all-rounder
• OpenAI Codex - GPT-4 based coding
• Amp (Sourcegraph) - Code intelligence

• OpenCode - Free, runs locally
• Qwen Code (Alibaba) - Open source
• Claude Router - LLM-agnostic, use ANY model

1. Single AI - Use just Claude or just Gemini
2. Free Agents - Use OpenCode or Qwen (100% free)
3. Pay-as-you-go - Most AI APIs are pay-per-use, not subscriptions

• Start with one AI (Claude Code or Gemini)
• Add more later to compare approaches
• Use free agents for experimentation

git checkout feature-branch  # Switches your code
# Risk: Can break your main branch

# Main repo stays on main branch
# Each task gets isolated worktree
.forge/worktrees/task-1-attempt-1/  # AI works here
.forge/worktrees/task-2-attempt-1/  # Another task here

# Your main codebase is never touched
# Review results, merge when ready

• Multiple tasks execute simultaneously
• Main branch stays clean
• Safe experimentation
• Easy rollback

Task: "Add user authentication"

Attempt 1: Claude Code → Comprehensive but complex
Attempt 2: Gemini → Simple but missing edge cases
Attempt 3: Cursor → Perfect balance ✅

You choose: Attempt 3 to merge

• Compare different approaches
• Learn which agent works best for what
• No risk (each in isolated worktree)
• Choose best implementation

• Git worktrees provide isolation
• Version control tracks changes
• Safe rollback if needed

cd your-project
git init
git add .
git commit -m "Initial commit"

# Now run Forge
automagik-forge

• Develop features locally
• Review AI-generated code
• Merge to main when approved

• GitHub Actions
• GitLab CI
• Jenkins
• etc.

• Claude Code
• Cursor
• VSCode + Cline
• Roo Code
• Gemini CLI
• Any MCP-compatible agent

1. Get your Project ID:
   cat .forge/config.json | grep project_id
   
2. Configure MCP server (example for Claude Code):
   {
     "mcpServers": {
       "automagik-forge": {
         "command": "npx",
         "args": ["automagik-forge", "--mcp"],
         "env": {
           "PROJECT_ID": "your-uuid-here"
         }
       }
     }
   }
   
3. Use from AI agent:
   "Create a new task: Add user authentication with JWT"
   "List all high-priority tasks"
   "Update task-123 status to done"
   

• Each developer runs their own Forge instance
• Tasks in personal Kanban
• Individual git worktrees

• Each person runs Forge locally
• Coordinate via GitHub/GitLab
• Share task templates and patterns
• Use same agents/settings across team

1. API Key Issues:
   # Verify API key is set
   echo $ANTHROPIC_API_KEY  # For Claude
   
   # Set if missing
   export ANTHROPIC_API_KEY=sk-ant-...
   
2. Git Issues:
   # Ensure you're in a git repo
   git status
   
   # Commit uncommitted changes
   git add .
   git commit -m "Save work"
   
3. Executor Not Configured:
   # Check executors enabled
   cat .forge/config.json | jq '.executors'
   
   # Enable in UI: Settings → Executors
   
4. Worktree Issues:
   # Clean up old worktrees
   git worktree prune
   rm -rf .forge/worktrees/*
   

• Settings → Cleanup → Remove Old Worktrees

# Remove all worktree directories
rm -rf .forge/worktrees/*

# Prune git references
git worktree prune

# Restart Forge
automagik-forge

// In .forge/config.json
{
  "worktrees": {
    "auto_delete_merged": true,
    "cleanup_on_exit": true
  }
}

• Many git worktrees (each is full code copy)
• Large git repository
• Many task attempts
• Database growth

1. Clean up worktrees:
   rm -rf .forge/worktrees/*
   git worktree prune
   
2. Clean up database:
   sqlite3 .forge/db.sqlite "DELETE FROM tasks WHERE status='done' AND updated_at < datetime('now', '-30 days');"
   sqlite3 .forge/db.sqlite "VACUUM;"
   
3. Enable auto-cleanup:
   {
     "worktrees": {
       "auto_delete_merged": true,
       "max_concurrent": 3
     }
   }
   

# Start backend only
BACKEND_PORT=5000 automagik-forge

# Access via API
curl http://server-ip:5000/api/projects

# Or use MCP mode
automagik-forge --mcp

• No web UI (can build separately and point to API)
• Need to manage via API or MCP only
• GitHub OAuth requires redirect to localhost

• Run Forge on your local machine
• Use git/GitHub to share code changes
• Each developer has own Forge instance

1. Report bugs:
   • https://github.com/namastexlabs/automagik-forge/issues
2. Suggest features:
   • GitHub Discussions or Discord
3. Submit pull requests:
   • Fork the repo
   • Create feature branch
   • Submit PR
4. Improve documentation:
   • Docs are in /docs directory
   • Submit PR with improvements
5. Join community:
   • Discord: https://discord.gg/xcW8c7fF3R
   • Help other users
   • Share templates and patterns

​

Q4 2024

• Template marketplace
• Task dependencies visualization
• UI revamp
• Analytics dashboard
• Spark integration (scheduled tasks)

​

Q1-Q2 2025

• Cross-Forge sync (share tasks)
• Hive executor (proprietary agent)
• Non-code workflows (docs, PPTs)
• Enterprise features
• Mobile companion app

​

Future

• AI intelligence layer
• Global template marketplace
• Industry verticals
• Cloud offering (optional SaaS)

• All data stored locally in .forge/ directory
• SQLite database (unencrypted)
• GitHub OAuth tokens encrypted

• Your code never leaves your machine
• Tasks stored locally only
• No telemetry (except optional PostHog)

1. Never commit .forge/ to git:
   .forge/
   .env
   
2. Restrict file permissions:
   chmod 600 .forge/config.json
   chmod 700 .forge/
   
3. Use environment variables for secrets:
   export ANTHROPIC_API_KEY=...
   # Not in config files
   
4. Backup important data:
   cp -r .forge .forge-backup