Skip to main content

​
Overview

Automagik Forge provides a command-line interface for starting the web UI, managing the MCP server, and running the backend programmatically.

​
Quick Start

# Install globally
npm install -g automagik-forge

# Or run directly with npx
npx automagik-forge

​
Main Command

The primary command launches the Forge web interface: 
automagik-forge [options]

​
Options

OptionDescriptionDefault
--mcpStart in MCP server mode (basic, 6 tools)Web UI mode
--mcp-advancedStart in MCP server mode (advanced, 56+ tools)Web UI mode
--port <port>Specify frontend port3000
--backend-port <port>Specify backend API portAuto-assigned
--host <host>Specify host address127.0.0.1

​
Usage Modes

  • Web UI Mode (Default)
  • MCP Server Mode
Launch the full Kanban interface:
# Start on default port (3000)
automagik-forge

# Custom port
automagik-forge --port 8080

# Custom backend port
automagik-forge --port 3000 --backend-port 5000
Opens browser at http://localhost:3000 with:
  • Visual Kanban board
  • Task management interface
  • Real-time execution logs
  • Project settings
  • GitHub integration

​
Environment Variables

Configure Forge behavior via environment variables: 
# Backend configuration
export BACKEND_PORT=5000
export HOST=0.0.0.0

# GitHub OAuth (optional)
export GITHUB_CLIENT_ID=your_client_id

# Analytics (optional)
export POSTHOG_API_KEY=your_posthog_key

# Debug options
export RUST_LOG=debug
export DISABLE_WORKTREE_ORPHAN_CLEANUP=1

​
Configuration File

Forge stores configuration in your project: 
# Initialize configuration
cd your-project
automagik-forge

# Creates .forge/ directory:
.forge/
├── config.json          # Main configuration
├── db.sqlite            # Task database
├── worktrees/           # Git worktrees for isolated execution
└── logs/                # Execution logs

​
config.json Structure

{
  "project_id": "uuid-here",
  "github": {
    "repository": "owner/repo",
    "token": "encrypted"
  },
  "worktrees": {
    "enabled": true,
    "base_path": "./.forge/worktrees",
    "cleanup_on_exit": true
  },
  "executors": {
    "default": "claude-code",
    "available": ["claude-code", "cursor-cli", "gemini", "codex"]
  }
}

​
Platform Support

Forge provides native binaries for multiple platforms:

Linux

  • x64 (Intel/AMD)
  • ARM64

macOS

  • x64 (Intel)
  • ARM64 (Apple Silicon)
  • Rosetta detection

Windows

  • x64
  • ARM64

​
Troubleshooting

If you installed globally but can’t run the command:
# Check NPM global bin path
npm config get prefix

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

# Find process using port
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Use different port
automagik-forge --port 8080

❌ Unsupported platform: linux-arm32
Forge supports:
  • Linux x64, Linux ARM64
  • macOS x64 (Intel), macOS ARM64 (Apple Silicon)
  • Windows x64, Windows ARM64
For unsupported platforms, build from source:
git clone https://github.com/namastexlabs/automagik-forge
cd automagik-forge
./local-build.sh

# Check if MCP server is running
ps aux | grep automagik-forge

# Check MCP server logs
cat ~/.forge/mcp-server.log

# Restart in MCP mode
automagik-forge --mcp

​
Programmatic Usage

While Forge is primarily a web UI, you can interact with it programmatically: Configure in your AI agent (Claude Code, Cursor, etc.): 
{
  "mcpServers": {
    "automagik-forge": {
      "command": "npx",
      "args": ["automagik-forge", "--mcp"],
      "env": {
        "PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

​
Via REST API

When Forge is running, it exposes a REST API: 
# Start Forge
automagik-forge --port 3000 --backend-port 5000

# API available at http://localhost:5000/api
curl http://localhost:5000/api/projects
curl http://localhost:5000/api/tasks
See API Reference for complete endpoints.

​
Next Steps

Project Commands

Manage projects and repositories

Task Commands

Create and manage tasks

Config Commands

Configuration management

MCP Tools Reference

Complete MCP tool documentation
Note: Forge is designed as a graphical web interface. The CLI primarily serves to launch the UI and provide MCP server functionality for AI agent integration.