The Vibe Coding++™ Platform for Human-AI Development

🎯 Where Vibe Coding Meets Structured Execution
Works with any AI coding tool through natural language, execute in isolated environments,
ship confident code with complete control and visibility

Features • Quick Start • Roadmap • Development • Contributing

---

🚀 What is Automagik Forge?

Automagik Forge is the vibe coding++ platform where humans stay in control. It's the structured home for your AI development tasks - plan them yourself or vibe with AI to create them, experiment with different agents to find what works, review everything before shipping. No more code that breaks in 2 weeks.

🎭 Vibe Coding++™ Philosophy

Regular vibe coding problem: You chat with AI, get code, ship it. Two weeks later? Everything breaks and you can't fix it because you let AI do everything.

Vibe Coding++™ solution: Perfect human-AI integration where you:

• 📋 You Plan Tasks: Break down work yourself or use AI to help plan
• 🏠 Forge is Home: All tasks live in persistent kanban, not lost in chat history or random .md files scattered across your codebase
• 🧪 You Experiment: Try different agents on same task - see what works best
• 🎯 You Choose Agents: Pick which coding agent AND specialized agent for each task
• 🔒 Isolated Attempts: Each attempt in its own Git worktree - no conflicts
• 👀 You Review: Understand what changed before merging
• 🚀 Ship Confident Code: Code that won't mysteriously break in 2 weeks

🚫 Why Regular Vibe Coding Fails

The "just let AI do it" approach creates a ticking time bomb:

• No Structure: Random chat conversations, no task tracking
• No Control: AI makes all decisions, you don't understand the code
• No Memory: What did we build last week? Who knows! Lost in chat history or random .md files
• No Experimentation: Stuck with one agent's approach
• The 2-Week Curse: Code works today, breaks tomorrow, unfixable forever

✅ The Vibe Coding++™ Solution

Forge elevates human potential - you orchestrate, AI executes:

• You Own the Kanban: Tasks you create, not AI's whims
• You Pick the Agent: Try Claude, then Gemini, see what works
• You Choose Specialization: Apply "test writer" or "PR reviewer" as needed
• Multiple Attempts: Each task can have multiple attempts with different agents
• Git Worktree Isolation: Every attempt isolated, no conflicts
• You Review & Understand: Know exactly what's changing before merge
• MCP Control: Create/update tasks from your coding agent without leaving your flow

---

🌟 Key Features

• 8 AI Coding Agents: Claude, Cursor CLI, Gemini, Codex, and more - including open-source options
• Specialized Agents: Custom prompts that work with ANY coding agent (test-writer, pr-reviewer, etc.)
• Multiple Attempts Per Task: Try different agents, compare results, choose the best
• Parallel Execution: Run multiple agents simultaneously on different tasks
• Git Worktree Isolation: Every attempt in its own isolated environment
• Persistent Kanban Board: Tasks live forever, not lost in chat history
• Task Templates: Reusable patterns for common workflows
• MCP Server Built-in: Control from any AI coding agent without leaving your flow
• Visual Context: Attach screenshots and diagrams to tasks
• Real-time Progress: Watch agents work, see diffs as they happen
• GitHub Integration: OAuth authentication and repository management
• 100% Open Source: Free forever, self-hostable, no vendor lock-in

---

🤖 Two Types of Agents, Clear and Simple

The Key Distinction:

• AI Coding Agents = The AI execution platforms (CLI tools that run AI models)
• Specialized Agents = Custom prompts that work with ANY coding agent
• Example: Your "test-writer" specialized agent can run on Claude today, Gemini tomorrow

🛠️ AI Coding Agents Available in Forge

Forge can execute tasks using these AI coding agents - including open-source and LLM-agnostic options:

• Claude Code - Anthropic's Claude models
• Claude Code Router - LLM-agnostic, use ANY model instead of Claude
• Cursor CLI - Cursor's CLI agent (separate from their IDE)
• Gemini - Google's Gemini models
• Codex - OpenAI's code models
• Amp - Sourcegraph's code intelligence
• OpenCode - Open-source models, fully local execution
• Qwen Code - Alibaba's open-source models

The Power: Not locked to subscriptions - use open-source models, route to any LLM, or bring your own API keys

🧪 Task Attempts: Experiment Until It Works

Each task can have multiple attempts - try different approaches:

Task: "Implement user authentication"
├── Attempt 1: Claude + "security-expert" → Too complex
├── Attempt 2: Gemini + default → Missing edge cases  
├── Attempt 3: Cursor + "auth-specialist" → Perfect! ✅
└── Result: You choose Attempt 3 to merge

The Power of Attempts:

• Each attempt runs in isolated Git worktree
• Compare different agent outputs side-by-side
• No commits until YOU approve
• Learn which agent works best for which task type

Available Templates:

• 🔍 Code Review: Multi-agent PR analysis
• 🐛 Bug Hunt: Reproduce → Fix → Test → Document
• ✨ Feature Dev: Design → Implement → Test → Deploy
• 🔧 Refactor: Analyze → Plan → Execute → Verify
• 📚 Documentation: Code → Comments → README → Examples

---

📸 Visual Context

Attach screenshots, diagrams, or mockups to any task - agents see the visual context and generate better solutions.

---

📡 MCP: Remote Control from Anywhere

Automagik Forge acts as a Model Context Protocol (MCP) server, enabling AI coding agents to programmatically manage tasks. Control your Forge task board from your preferred AI coding agent without leaving your flow.

Typical Workflow

1. Planning Phase: Use your AI agent to help brainstorm and plan tasks
2. Task Creation: You (or your agent) creates task cards via MCP
3. Bug Discovery: Find issues while coding? Add them to the backlog via MCP
4. Status Updates: Update task progress as work completes
5. Cross-Agent Access: Any MCP-compatible agent can access your task board

Example Use Cases

• 🎯 "Help me plan a complete authentication system with OAuth, JWT, and role-based access" → You create epic with subtasks
• 🐛 "Add bug: API returns 500 on malformed JSON input in /api/users endpoint" → Create detailed bug card via MCP
• ✅ "Mark all database migration tasks as complete and move API tasks to in-progress" → Batch update statuses via MCP
• 📋 "Show me all high-priority tasks that are blocked or have dependencies" → Query tasks with filters via MCP

Available MCP Tools

Tool	Description	Example Usage
list_projects	Get all projects	"List all my active projects"
list_tasks	View tasks with filters	"Show pending backend tasks"
create_task	Add new task to project	"Create task: Implement Redis caching layer"
get_task	Get detailed task info	"Show details for task-abc123"
update_task	Modify task properties	"Move task-xyz to in-review"
delete_task	Remove completed/obsolete tasks	"Delete all cancelled tasks"

Quick Setup

Getting Your Project ID

1. Run npx automagik-forge to open the UI
2. Create or select your project
3. The Project ID (UUID) appears in:
   • The browser URL: http://localhost:3000/projects/{PROJECT_ID}/tasks
   • The project settings panel
   • Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

🤖 Claude Code Configuration

1. Open Claude Code settings
2. Navigate to MCP Servers section
3. Add Forge server configuration:

{
  "mcpServers": {
    "automagik-forge": {
      "command": "npx",
      "args": ["automagik-forge", "mcp-server"],
      "env": {
        "PROJECT_ID": "your-project-uuid-here"
      }
    }
  }
}

4. Restart Claude Code
5. Use natural language: "Create tasks for implementing a real-time chat feature"

🎯 Cursor Configuration

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP" in settings
3. Add to MCP configuration:

{
  "mcp.servers": {
    "automagik-forge": {
      "command": "npx",
      "args": ["automagik-forge", "mcp-server"],
      "projectId": "your-project-uuid-here"
    }
  }
}

4. Reload window (Cmd/Ctrl + R)
5. Tasks are now accessible via @automagik-forge

📝 VSCode + Cline Configuration

For Cline Extension:

1. Install Cline from VSCode marketplace
2. Open Cline settings (Cmd/Ctrl + Shift + P → "Cline: Settings")
3. Add MCP server:

{
  "cline.mcpServers": [
    {
      "name": "automagik-forge",
      "command": "npx",
      "args": ["automagik-forge", "mcp-server"],
      "env": {
        "PROJECT_ID": "your-project-uuid-here"
      }
    }
  ]
}

4. Restart VSCode
5. Cline can now manage tasks directly

🚀 Roo Code Configuration

1. Open Roo Code preferences
2. Navigate to Extensions → MCP
3. Add new server:

servers:
  automagik-forge:
    command: npx
    args: 
      - automagik-forge
      - mcp-server
    environment:
      PROJECT_ID: your-project-uuid-here

4. Save and restart Roo Code
5. Access via command palette: "Roo: Create Task"

💎 Gemini CLI Configuration

1. Edit Gemini CLI config file (~/.gemini/config.json)
2. Add MCP server entry:

{
  "mcp": {
    "servers": {
      "automagik-forge": {
        "type": "stdio",
        "command": "npx",
        "args": ["automagik-forge", "mcp-server"],
        "env": {
          "PROJECT_ID": "your-project-uuid-here"
        }
      }
    }
  }
}

3. Run: gemini reload-config
4. Use: gemini task create "Implement user dashboard with charts"

🔧 Generic MCP Configuration

For any MCP-compatible tool, use this standard configuration:

{
  "command": "npx",
  "args": ["automagik-forge", "mcp-server"],
  "env": {
    "PROJECT_ID": "your-project-uuid-here"
  }
}

Tool-Specific Paths:

• Check your tool's MCP or extensions documentation
• Look for "MCP Servers", "External Tools", or "Model Context Protocol" settings
• The configuration format is typically JSON or YAML

---

🎭 Vibe Coding++™ Workflows

Human Orchestration, Not AI Automation

graph LR
    A[You Plan Tasks] --> B[You Choose Agents]
    B --> C[Try Multiple Attempts]
    C --> D[Compare Results]
    D --> E[You Review & Decide]
    E --> F[Ship Clean PRs]

Loading

Example: Building a Feature

You: "I need a user dashboard with charts and real-time updates"

Your Process:
1. YOU create tasks (or use AI to help plan):
   ├── Task 1: Design dashboard layout
   ├── Task 2: Create chart components  
   ├── Task 3: Build WebSocket service
   ├── Task 4: Write integration tests
   └── Task 5: Generate documentation

2. YOU experiment with different agents:
   Task 2 - Chart Components:
   ├── Attempt 1: Try Claude → Too abstract
   ├── Attempt 2: Try Cursor → Good but verbose
   └── Attempt 3: Try Gemini → Perfect! ✅
   
3. YOU review and choose what to merge

The Power: You're in control, not hoping AI gets it right

---

📊 Vibe Coding vs Vibe Coding++™

Feature	Forge (Vibe Coding++™)	Lovable (Regular Vibe Coding)
Human Control	✅ You orchestrate every decision	❌ AI acts autonomously
Task Persistence	✅ Kanban board - tasks live forever	❌ Lost in chat conversations
Multiple Attempts	✅ Try different agents per task	❌ One AI, one approach
8 AI Coding Agents	✅ Claude, Cursor CLI, Gemini, etc.	❌ Single AI model
Specialized Agents	✅ Custom prompts for any agent	❌ Fixed behavior
Git Worktree Isolation	✅ Every attempt isolated	❌ Direct code changes
MCP Server	✅ 6 tools for remote control	❌ No external integration
2-Week Curse Protection	✅ You understand the code	❌ AI black box magic
Code Review	✅ Review before merge	❌ Auto-applies changes
Visual Context	✅ Attach screenshots to tasks	✅ Can generate images
Open Source	✅ 100% open-source	❌ Proprietary
Pricing Model	✅ Free forever	💰 Usage-based credits
Self-Hostable	✅ Your infrastructure	❌ Cloud-only

---

📦 Quick Start

Prerequisites

• Node.js 18+ and pnpm 8+
• Authenticated AI coding agent (Claude Code, Gemini CLI, etc.)
• Git repository to work with

Installation

# Install globally
npm install -g automagik-forge

# Or run directly with npx
npx automagik-forge

First Run

# Navigate to your project
cd your-project

# Launch Forge
automagik-forge

# Open browser to http://localhost:3000

---

🛠️ Development

Interested in contributing or building from source? Check out our Developer Guide for detailed instructions on:

• Setting up the development environment
• Building from source
• Running tests
• Database migrations
• Architecture details

---

🗺️ Roadmap

Completed ✅

• Multi-agent orchestration
• Kanban task management
• Git worktree isolation
• MCP server implementation
• Real-time progress streaming

Next Up 🚀

• Wish System & Genie - Natural language wishes become epics with subtasks, interactive AI assistant navigates the UI
• Bilateral sync - Two-way sync with GitHub Issues, Jira, Notion, Linear
• Epics & Subtasks - Hierarchical task organization with dependency management
• Agent performance analytics
• Team collaboration features
• Community templates
• Integration with CI/CD pipelines

---

🤝 Contributing

We love contributions! However, to maintain project coherence:

1. Discuss First: Open an issue before starting work
2. Align with Roadmap: Ensure changes fit our vision
3. Follow Standards: Match existing code patterns
4. Test Thoroughly: Include tests for new features
5. Document Well: Update docs with your changes

See CONTRIBUTING.md for detailed guidelines.

🙏 Acknowledgments

Special thanks to:

• Vibe Kanban team, whose original vision inspired Automagik Forge's evolution.
• All our early adopters and contributors

---

📄 License

MIT License - see LICENSE file for details.

---

🔗 Links

• Website: forge.automag.ik
• NPM Package: npmjs.com/package/automagik-forge
• GitHub: github.com/namastexlabs/automagik-forge
• Discord: discord.gg/automagik
• Twitter: @automagikdev

---

🚀 Stop the 2-week curse. Start shipping code you actually understand.
Vibe Coding++™ - Where Human Control Meets AI Power

Star us on GitHub • Join our Discord •

Made with ❤️ by Namastex Labs
AI that elevates human potential, not replaces it