Install claw-forge

We use uv for fast, isolated installation. It puts the claw-forge command on your PATH without polluting your system Python.

pip install uv
uv tool install claw-forge
claw-forge --version

pip install pipx
pipx install claw-forge
claw-forge --version

pip install claw-forge
claw-forge --version

Set up environment variables

claw-forge reads credentials from environment variables. Copy the example file and fill in your keys:

cp .env.example .env
# Edit .env with your editor

The minimum you need to get started is one of the following:

# Run claude login once — claw-forge picks it up automatically.
# No env vars needed for OAuth. Token is read from:
#   ~/.claude/.credentials.json
claude login

# .env
ANTHROPIC_API_KEY_1=sk-ant-api03-...

# .env — Anthropic-compat proxy
PROXY_1_API_KEY=your-proxy-key
PROXY_1_BASE_URL=https://your-proxy.example.com/v1
PROXY_1_MODEL=claude-sonnet-4-6

claw-forge automatically loads .env from the same directory as claw-forge.yaml — no export or source needed.

Configure providers

Create claw-forge.yaml in your project root. Every credential is read from env vars — never hardcode keys.

pool:
  strategy: priority
  max_retries: 3

providers:
  claude-oauth:
    type: anthropic_oauth
    priority: 1
    # Token auto-read from ~/.claude/.credentials.json

pool:
  strategy: priority
  max_retries: 3

providers:
  claude-oauth:
    type: anthropic_oauth
    priority: 1

  anthropic-primary:
    type: anthropic
    api_key: ${ANTHROPIC_API_KEY_1}
    priority: 2

  groq-backup:
    type: openai_compat
    api_key: ${GROQ_API_KEY}
    base_url: https://api.groq.com/openai/v1
    model: llama-3.3-70b-versatile
    priority: 3

pool:
  strategy: priority
  max_retries: 3

providers:
  # Anthropic-format proxy (x-api-key + /v1/messages)
  anthropic-proxy-1:
    type: anthropic_compat
    api_key: ${PROXY_1_API_KEY}
    base_url: ${PROXY_1_BASE_URL}
    model: ${PROXY_1_MODEL}
    priority: 1

  anthropic-proxy-2:
    type: anthropic_compat
    api_key: ${PROXY_2_API_KEY}
    base_url: ${PROXY_2_BASE_URL}
    model: ${PROXY_2_MODEL}
    priority: 2

pool:
  strategy: priority
  max_retries: 3

providers:
  # Ollama — local model, zero cost
  local-ollama:
    type: ollama
    base_url: ${OLLAMA_BASE_URL}
    model: ${OLLAMA_MODEL}
    priority: 1
    cost_per_mtok_input: 0.0
    cost_per_mtok_output: 0.0

  # .env:
  # OLLAMA_BASE_URL=http://localhost:11434
  # OLLAMA_MODEL=qwen2.5-coder

The pool manager routes each request through providers in priority order, skipping any that are rate-limited or have open circuit breakers.

Bootstrap your project

Run claw-forge init first — before writing a spec. This scaffolds the .claude/commands/ folder (including the /create-spec slash command you'll need in the next step) and creates default config files if they don't exist yet.

cd my-project
claw-forge init

# Or bootstrap a specific directory without cd:
claw-forge init --project ~/projects/my-app

Write your project spec

Now that .claude/commands/ exists, open Claude Code in your project directory and use the /create-spec command — or write the spec manually. The spec describes what you want to build; the init agent reads it and breaks it into parallel tasks.

You have three ways to create a spec:

Option A — Write app_spec.txt yourself

The format is human-readable and intentionally flexible. The key thing is to be specific about acceptance criteria — vague features produce vague code.

Option B — Interactive spec with /create-spec

Open Claude Code in your project directory and type /create-spec. Claude will walk you through the project conversationally — asking about your stack, features, providers, and concurrency — then write both app_spec.txt and claw-forge.yaml for you.

# Open your project in Claude Code, then type:
/create-spec

Option C — Convert an existing PRD

If you already have a PRD, Notion export, or detailed README, claw-forge init copies app_spec.example.xml into your project so Claude knows the exact format. Paste your PRD into Claude and use this prompt:

Because app_spec.example.xml is already in the project directory, Claude Code reads it automatically and produces valid XML — no guessing the format.

Initialize with your spec

Now run claw-forge plan app_spec.txt. The initializer agent reads your spec, analyzes the project directory, and creates a dependency-ordered task graph in the state database.

claw-forge plan app_spec.txt --project task-manager-api

The initializer also writes .claw-forge/session_manifest.json — a pre-computed context blob that every subsequent agent session loads at start. This eliminates cold-start: agents don't re-analyse the project from scratch each time.

What the manifest contains

You can inspect it any time:

cat .claw-forge/session_manifest.json

Run agents

Start the harness. The dispatcher executes features in dependency-ordered waves — features with no unsatisfied dependencies run in parallel up to --concurrency.

claw-forge run --project task-manager-api --concurrency 3

The state service runs automatically on port 8420. Open http://localhost:8420/docs to explore the REST API, or use the Kanban UI (next step).

claw-forge pool-status   # show all providers, rate limits, and health

Open the Kanban UI

claw-forge ships a React Kanban board that shows real-time agent progress, provider health, and cost. Launch it with one command:

claw-forge ui --session abc-123-def

The board opens automatically in your browser:

What you'll see:

• 5 columns: Pending · In Progress · Passing · Failed · Blocked
• Provider health dots in the header — click any dot for RPM, latency, circuit state, and cost
• Progress bar — X/Y features passing, live
• Cost tracker — total USD spent this session
• Feature cards — show category badge, dep count, agent session ID when running, error message when failed

claw-forge ui --port 3000        # custom port
claw-forge ui --no-open          # don't auto-open browser
claw-forge ui --state-port 9000  # different state service port

claw-forge dev                          # state API + Vite UI, both with hot-reload
claw-forge dev --state-port 9000 --ui-port 3000   # custom ports
claw-forge dev --project /path/to/project --run   # also run agents

You can also open the board manually at any time at http://localhost:5173/?session=<uuid>.

Add more features

Once your first batch of features is running (or done), add more without restarting. There are two ways:

Option A — /expand-project slash command

Open Claude Code in your project directory and type /expand-project. Claude will list the current features, ask what you want to add, and POST them to the state service atomically.

/expand-project

Option B — append to app_spec.txt and re-init

Add new entries to the bottom of your spec file and run init again. Only new features (those not already in the DB) will be created.

# Append to app_spec.txt, then:
claw-forge plan app_spec.txt --project task-manager-api

YOLO mode — maximum speed 🚀

YOLO mode enables three things at once:

• Max concurrency — set to your CPU count automatically
• Auto-approve human inputs — agents never pause waiting for you
• Aggressive retry — 5 attempts per task instead of 3

claw-forge run --project task-manager-api --yolo

Pause & resume

Pause a running session gracefully — in-flight agents finish their current task, then no new ones start. Resume picks up exactly where it stopped.

# Pause (drain mode — active agents complete, no new ones start)
claw-forge pause abc-123-def

# Resume
claw-forge resume abc-123-def

Answer a stuck agent

If an agent has a question it can't answer on its own (a missing env var, an ambiguous requirement), it sets the task to needs_human and waits. Use claw-forge input to unblock it:

claw-forge input abc-123-def