📦 Quick Start

Prerequisites

  • Node.js 18+ and pnpm 8+ (tested with pnpm 10.12.4)
  • 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 (browser opens automatically to http://localhost:8887)
automagik-forge

🚀 What is Automagik Forge?

Automagik Forge is the vibe coding++ platform where humans stay in control. It's the structured home for your AI-powered tasks - plan them yourself or use Genie to help, experiment with different providers and agents to find what works, review everything before shipping. Perfect for development, content, and any AI-assisted work.

🎭 Vibe Coding++™ Philosophy

Regular vibe coding problem: You chat with AI, get output, ship it. Two weeks later? Things break and you can't fix them because you let AI do everything without understanding.

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

  • 📋 You Plan Tasks: Break down work yourself or use Genie AI assistant 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 providers and agents on same task - see what works best
  • 🎯 You Choose: Pick which provider (Claude, Gemini, etc.) and agent (test-writer, security-expert) for each task
  • 🔒 Isolated Attempts: Each attempt in its own Git worktree - no conflicts
  • 👀 You Review: Understand what changed before merging
  • 🚀 Ship with Confidence: Work you understand and can maintain

🚀 The 10x Productivity Advantage

Forge delivers exponential productivity through intelligent parallelism:

  • Run Multiple Tasks Simultaneously: While one agent writes tests, another fixes bugs, and a third refactors code
  • Never Wait: No sequential bottleneck - scale your output by running many agents at once
  • Total Visibility: Every task, every attempt, every change tracked and visible in one place
  • Nothing Forgotten: Persistent kanban means no work is lost, everything has context
  • Structured Execution: Tasks you control, not scattered in chat history or random .md files

✅ 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 Provider + Agent: Try Claude with test-writer agent, then Gemini with security agent
  • Multiple Attempts: Each task can have multiple attempts with different providers/agents
  • Genie AI Assistant: Optional .genie integration for AI-assisted planning and custom 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

🎯 The Wish → Forge → Review Framework

Forge uses a three-phase workflow that maps directly to the kanban columns:

1. Wish (Planning Phase)

  • Create tasks yourself or use Genie AI assistant to help break down complex work
  • Define clear requirements and acceptance criteria
  • Attach screenshots, diagrams, and context
  • Tasks live in "Wish" column until you're ready to execute

2. Forge (Execution Phase)

  • Pick your provider (Claude, Gemini, etc.) and agent (test-writer, security-expert, etc.)
  • Execute tasks in isolated Git worktrees - run multiple tasks in parallel
  • Watch real-time progress, see diffs as they happen
  • Create multiple attempts with different providers/agents to find what works best
  • Tasks move to "Forge" column during execution

3. Review (Validation Phase)

  • Compare attempts side-by-side, understand what changed
  • Review diffs, run tests, validate quality
  • Choose the best attempt to merge
  • Ship with confidence - work you understand and can maintain
  • Tasks move to "Review" column when ready for your approval

The Power:

  • Total Control: You orchestrate, AI executes
  • Maximum Parallelism: Run many tasks simultaneously for 10x productivity
  • Complete Visibility: Nothing is hidden, everything tracked
  • No Surprises: Review before merge, understand before ship

🌟 Key Features

  • 8 AI Providers: Claude Code, Cursor, Gemini, Codex, and more - including open-source options
  • Custom Agents: Add specialized behavior to any provider (test-writer, security-expert, refactor-specialist, content-writer)
  • Genie Integration: Auto-detects .genie folders and activates Genie Lamp for AI assistant capabilities
  • Multiple Attempts Per Task: Try different providers and 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
  • 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

🤖 Providers + Agents: Two-Layer Flexibility

🛠️ How It Works

Layer 1: Providers (Who executes the task)

  • Claude Code - Anthropic's Claude models (supports Router for any LLM)
  • Cursor - Cursor's AI capabilities
  • Gemini - Google's Gemini models
  • Codex - OpenAI's models
  • Amp - Sourcegraph's code intelligence
  • OpenCode - Open-source models, fully local
  • Qwen Code - Alibaba's open-source models
  • Copilot - GitHub Copilot integration

Layer 2: Agents (How they should behave)

  • Add specialized behavior to any provider via custom prompts
  • Create agents for any purpose: "test-writer", "security-expert", "content-writer", "documentation-specialist"
  • Agents work with ANY provider - same behavior, different AI model

Example: Your "test-writer" agent can run on Claude today, Gemini tomorrow, or your local LLM next week.

The Power: Not locked to subscriptions - use open-source models, route to any LLM, bring your own API keys, customize for coding OR general tasks

🧪 Task Attempts: Experiment Until It Works

Each task can have multiple attempts - try different approaches:

Task: "Implement user authentication"
├── Attempt 1: Claude Code → Too complex
├── Attempt 2: Gemini → Missing edge cases
├── Attempt 3: Cursor Agent → 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

🧞 Genie Integration: Your AI Assistant

Forge works seamlessly with Automagik Genie for AI-assisted task planning and execution.

Setup:

npm install -g automagik-genie
cd your-project
genie init

What You Get:

  • Master Genie Widget: AI assistant for planning and breaking down complex work
  • Custom Agents: Backend auto-loads agents from .genie/agents/ directory
  • Unified Workflow: Plan with Genie MCP, execute in Forge, review results

Integration Status:

  • ✅ Backend: Auto-detects .genie folder, loads custom agents, hot-reloads on changes
  • 🚧 Frontend: Master Genie widget available, full agent UI coming soon

Learn more: github.com/namastexlabs/automagik-genie

📡 MCP: AI Assistant Integration

Control Forge from your AI coding tools using Model Context Protocol (MCP).

🧞 Genie MCP (Recommended)

Natural language AI assistant for planning and managing Forge tasks.

npm install -g automagik-genie

Claude Desktop config:

{
  "mcpServers": {
    "genie": {
      "command": "genie",
      "args": ["mcp"]
    }
  }
}

What you can do:

  • "Help me plan an authentication system" → Creates organized tasks
  • "Run code agent on task-123" → Executes Forge tasks
  • "Show active sessions" → Monitor all work in progress

Direct API control for power users. Full programmatic access to all Forge features.

Command: npx @automagik/forge --mcp

Config example:

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

Tools: Task CRUD, attempts, processes, images, filesystem, config, and more.

Get Project ID: Open Forge UI, check browser URL: /projects/{PROJECT_ID}/tasks

🎭 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]

Example: Building a Feature

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

Your Process:
1. YOU create tasks (or use Genie 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 providers + agents:
   Task 2 - Chart Components:
   ├── Attempt 1: Claude Code (default) → Too abstract
   ├── Attempt 2: Cursor (refactor agent) → Good but verbose
   └── Attempt 3: Gemini (component-specialist agent) → 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 providers/agents per task ❌ One AI, one approach
8 AI Providers ✅ Claude Code, Cursor, Gemini, etc. ❌ Single AI model
Custom Agents ✅ Add specialized behavior to any provider ❌ Fixed behavior
Genie Integration ✅ Auto-detects .genie, activates Lamp ❌ No AI assistant integration
Git Worktree Isolation ✅ Every attempt isolated ❌ Direct changes
MCP Server ✅ 8+ tools for remote control ❌ No external integration
2-Week Curse Protection ✅ You understand the work ❌ 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

🛠️ Development

Quick Start

# Clone the repository
git clone https://github.com/namastexlabs/automagik-forge.git
cd automagik-forge

# Copy environment example (optional - only needed for custom ports)
cp .env.example .env

# Start development server
make dev

# Or build and test production package
make prod

Port Configuration:

  • Copy .env.example to .env to customize ports
  • Defaults work out of the box - no configuration needed!
  • Everything else is automated!

See also: DEVELOPER.md for architecture details and advanced topics

Upstream Management

Automagik Forge uses a mechanical rebranding approach to stay in sync with the upstream vibe-kanban template:

Architecture:

  • upstream/ - Git submodule pointing to namastexlabs/vibe-kanban fork
  • namastexlabs/vibe-kanban - Fork that mirrors BloopAI/vibe-kanban
  • scripts/rebrand.sh - Converts all vibe-kanban references to automagik-forge
  • forge-core/ - Core services (profiles, config) migrated from extensions
  • Minimal forge-overrides/ - Only feature files, no branding

Complete Workflow: Sync fork → Create namastex tag → Update gitmodule → Rebrand → Verify & commit

Updating to New Version

Automated (recommended):

# From automagik-forge repo
mcp__genie__run agent="utilities/upstream-update" prompt="Update to v0.0.106"

Manual:

# 1. Sync fork (in namastexlabs/vibe-kanban repo)
git remote add upstream https://github.com/BloopAI/vibe-kanban.git
git fetch upstream --tags
LATEST_TAG=$(git tag --list 'v0.0.*' --sort=-version:refname | head -1)
git reset --hard upstream/main
git push origin main --force

# 2. Create namastex release tag
NAMASTEX_TAG="${LATEST_TAG%-*}-namastex"
git tag -a $NAMASTEX_TAG -m "Namastex release based on $LATEST_TAG"
git push origin $NAMASTEX_TAG
gh release create $NAMASTEX_TAG --repo automagik.dev/vibe-kanban --title "$NAMASTEX_TAG" --notes "Based on $LATEST_TAG"

# 3. Update gitmodule (in automagik-forge repo)
cd upstream
git fetch origin --tags
git checkout $NAMASTEX_TAG
cd ..

# 4. Apply mechanical rebrand
./scripts/rebrand.sh

# 5. Verify success
grep -r "vibe-kanban" upstream frontend | wc -l  # Must be 0
cargo check --workspace
cd frontend && pnpm run check

# 6. Commit changes
git add -A
git commit -m "chore: update upstream to $NAMASTEX_TAG and rebrand"

Total time: ~3-5 minutes. Full automation via agent!

🗺️ 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

🧪 E2E Testing with Playwright

Forge uses Playwright for end-to-end testing with an LLM-friendly approach:

Running Tests

# Run all tests
pnpm test:e2e

# Run with UI mode (visual debugging)
pnpm test:e2e:ui

# Run in headed mode (see browser)
pnpm test:e2e:headed

# Debug mode (step through tests)
pnpm test:e2e:debug

Writing Tests

Our E2E tests follow user journey patterns - complete flows from start to finish:

  • See tests/e2e/USER-JOURNEYS.md for documented user journeys
  • Use tests/e2e/journey-create-task.spec.ts as a template
  • Follow the framework guide in tests/e2e/README.md

Why Playwright?

  • ✅ Real browser events (no synthetic event issues)
  • ✅ Auto-wait built-in (no manual timeouts)
  • ✅ Accessibility-first selectors (semantic, non-invasive)
  • ✅ Excellent debugging (screenshots, videos, time-travel traces)

🤝 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