Forge CLI

Parallel AI task runner with git worktrees, multi-provider support, and Linear integration.

Quickstart

# Install
npm install -g forge-cli

# Setup
cd your-repo
forge init

# Start the dashboard
forge ui

Features

• Parallel task execution — Run multiple AI tasks in isolated git worktrees
• Multi-provider — Claude Code CLI, Anthropic API, or bring your own
• Agent Teams — Dark Factory pipeline with role-specific providers (planner, implementer, reviewer, tester)
• Supervised & Auto modes — Human-in-the-loop review gates or fully autonomous
• Linear integration — Bi-directional sync with Linear issues
• Blueprint integration — Import scene graphs, create tasks from components
• Project registry — Manage multiple Forge instances across machines
• Real-time UI — Web dashboard with SSE-powered live updates

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  CLI / UI   │────▶│  Engine      │────▶│  Provider   │
│  (forge.mjs)│     │  (engine.mjs)│     │  (abstract) │
└─────────────┘     └──────┬───────┘     └──────┬──────┘
                           │                     │
                    ┌──────┴───────┐      ┌──────┴──────┐
                    │  Runner      │      │ Claude Code │
                    │  (runner.mjs)│      │ Anthropic   │
                    └──────────────┘      └─────────────┘

Task Lifecycle

queued → planning → [plan_review] → implementing → reviewing → [impl_review] → done → merged

• supervised — Pauses at plan_review and impl_review for human approval
• auto — Runs through without human gates (with test validation)
• manual — Creates worktree, you drive

Configuration

forge init  # Interactive setup

Or edit .forge/config.json:

{
  "provider": "claude-code",
  "defaultMode": "supervised",
  "defaultProfile": "default",
  "parallel": 5,
  "port": 3456,
  "providers": {
    "anthropic-api": {
      "type": "anthropic-api",
      "apiKey": "sk-ant-...",
      "model": "claude-sonnet-4-6"
    }
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | FORGE_PORT | Server port | 3456 | | FORGE_AUTH_TOKEN | Bearer token for LAN auth | — | | FORGE_PROVIDER | AI provider | claude-code | | FORGE_MODE | Default mode | supervised | | FORGE_PROFILE | Prompt profile | default | | FORGE_PARALLEL | Max concurrent tasks | 5 | | FORGE_TIMEOUT | Claude timeout (ms) | 600000 | | FORGE_SUPERVISED_TIMEOUT | Review timeout (hours) | 24 | | LINEAR_API_KEY | Linear API token | — | | ANTHROPIC_API_KEY | Anthropic API key | — |

Agent Teams

Configure team roles in .forge/team.json:

{
  "name": "feature-squad",
  "roles": {
    "planner": { "provider": "anthropic-api", "model": "claude-opus-4-6" },
    "implementer": { "provider": "claude-code" },
    "reviewer": { "provider": "anthropic-api", "model": "claude-sonnet-4-6" },
    "tester": { "provider": "anthropic-api", "model": "claude-haiku-4-5" }
  }
}

forge team start ENG-42  # Dark Factory pipeline
forge team config        # View team roles

Multi-Project Registry

forge registry add untap http://192.168.1.10:3456 --machine=macbook
forge registry list
forge registry remove untap

Projects auto-register when you run forge ui.

CLI Reference

Task Management

forge start <id...> [--mode=M] [--profile=P]  # Start tasks
forge list                                      # List all tasks
forge watch <id>                                # Stream task logs
forge accept <id>                               # Merge completed task
forge reject <id>                               # Reject implementation
forge revise <id>                               # Request revision
forge abort <id>                                # Cancel running task
forge restart <id>                              # Restart failed task

Pipeline Control

forge approve-plan <id>   # Approve plan, start implementation
forge revise-plan <id>    # Revise the plan
forge approve <id>        # Approve implementation
forge request-review <id> # Re-run code review

Setup & Config

forge init         # Interactive project setup
forge ui [--lan]   # Start web dashboard
forge create       # Create a local task
forge comment <id> # Add comment to task

API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Server health + task counts | | GET | /api/tasks | List all tasks | | POST | /api/tasks/start | Start task execution | | GET | /api/tasks/:id/plan | View task plan | | GET | /api/tasks/:id/diff | View code changes | | POST | /api/tasks/:id/approve-plan | Approve plan | | POST | /api/tasks/:id/approve-impl | Approve implementation | | POST | /api/tasks/:id/accept | Merge task | | POST | /api/tasks/:id/reject | Reject task | | POST | /api/teams/start | Start team pipeline | | GET | /api/teams/config | View team config | | POST | /api/graph/import | Import Blueprint graph | | GET | /api/graph/status | Graph task status | | GET | /api/events | SSE event stream |

License

MIT