npm package: @jvelez79/forge-cli
Description: Parallel AI task runner with git worktrees and Linear integration
Latest version: 0.8.2

# Forge CLI

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

## Quickstart

```bash
# 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

```bash
forge init  # Interactive setup
```

Or edit `.forge/config.json`:

```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`:

```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" }
  }
}
```

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

## Multi-Project Registry

```bash
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
```bash
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
```bash
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
```bash
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