claw-forge CLI

claw-forge is a multi-provider autonomous coding agent harness.
Agents run in parallel, claim features from a dependency DAG, and keep working until every feature passes — or you stop them.

GitHub: https://github.com/clawinfra/claw-forge
PyPI: https://pypi.org/project/claw-forge/

Install

pip install claw-forge
# or (recommended):
uv pip install claw-forge

Full Workflow

1 — Bootstrap a project

cd my-project
claw-forge init

Creates:

• CLAUDE.md

  — agent instructions (stack-aware)

• .claude/

  — slash commands (

  /create-spec

  , etc.)

• claw-forge.yaml

  — provider pool config

• .env.example

  — API key template

2 — Write a spec

Create

app_spec.txt

app_spec.xml

Project: My App
Stack: Python, FastAPI, SQLite

Authentication:
- JWT login endpoint
- Token refresh
- Session management

Dashboard:
- Real-time stats via WebSocket
- Export CSV

Or use the Claude slash command inside Claude Code:

/create-spec

3 — Plan: parse spec → feature DAG

claw-forge plan app_spec.txt

• Decomposes spec into atomic features
• Assigns dependency edges (A must pass before B starts)
• Writes task graph to

  .claw-forge/state.db

• Uses Opus by default (planning is the most critical step)

# Use Sonnet if cost matters more
claw-forge plan app_spec.txt --model claude-sonnet-4-6

4 — Run agents

claw-forge run

Default: 5 parallel coding agents, reads

claw-forge.yaml

# More concurrency
claw-forge run --concurrency 8

# Pin a specific model
claw-forge run --model claude-opus-4-6

# YOLO mode — skip human-input gates, max speed, aggressive retry
claw-forge run --yolo

# Preview without executing
claw-forge run --dry-run

# Use hashline edit mode (better for weaker models — 6.7%→68.3% benchmark)
claw-forge run --edit-mode hashline

5 — Check progress

claw-forge status

Shows: passing/failing/running/pending feature counts, recommended next action.

6 — Open the Kanban UI

claw-forge ui

Opens a browser-based Kanban board at

http://localhost:8888

All Commands

init

plan <spec>

run

status

ui

dev

add <spec>

pause

resume

fix <desc>

merge

input

pool-status

state

Config:

claw-forge.yaml

# Provider pool — add as many as you have keys for
providers:
  anthropic-primary:
    type: anthropic
    api_key: ${ANTHROPIC_API_KEY}
    priority: 1
    enabled: true
    max_rpm: 50
    model: claude-sonnet-4-6

  anthropic-backup:
    type: anthropic
    api_key: ${ANTHROPIC_API_KEY_2}
    priority: 2
    enabled: true
    max_rpm: 30
    model: claude-sonnet-4-6

# Pool routing strategy
pool:
  strategy: priority       # priority | round_robin | least_cost

# Model aliases (use in --model flag)
model_aliases:
  fast: claude-haiku-4-5
  smart: claude-opus-4-6
  default: claude-sonnet-4-6

# Git integration
git:
  enabled: true
  merge_strategy: auto     # auto | squash | merge

Edit Modes

str_replace

(default)

Standard exact-text matching. Works well with capable models (Sonnet, Opus).

hashline

(recommended for weaker models)

Content-addressed line tagging. Each line gets a 3-char hash prefix.
Model references lines by hash — immune to whitespace/indentation drift.
Benchmark: 6.7% → 68.3% success rate improvement on Grok Code Fast.

claw-forge run --edit-mode hashline

Brownfield (add to existing project)

# Write additions spec
cat > additions_spec.xml << 'EOF'
<project_specification>
  <project_name>my-app</project_name>
  <features_to_add>
    <auth>
      - Add OAuth2 Google login
      - Add rate limiting to auth endpoints
    </auth>
  </features_to_add>
</project_specification>
EOF

claw-forge add additions_spec.xml

Bug Fix Protocol

# Reproduce-first: agent writes failing test, then fixes it
claw-forge fix "Login fails when email has uppercase letters"

Common Patterns

Quick greenfield project

mkdir my-api && cd my-api
claw-forge init
# write app_spec.txt
claw-forge plan app_spec.txt
claw-forge run --concurrency 3
claw-forge status

Cost-optimised run

# Mix cheap + expensive: cheap model in pool for simple tasks
claw-forge run --model claude-haiku-4-5 --concurrency 10

Multi-provider failover

# Add multiple providers to claw-forge.yaml
# Pool auto-fails over on rate limits or errors
claw-forge pool-status    # check health
claw-forge run            # runs with automatic failover

YOLO overnight run

claw-forge run --yolo --concurrency 8
# Come back in the morning — all features should be passing

Tips

• Planning quality = outcome quality. Don't skimp on the planning model. Use Opus for

  plan

  .
• More concurrency ≠ always better. Each agent needs context. 3–5 is usually the sweet spot.

• --edit-mode hashline

  dramatically helps weaker/cheaper models that struggle with exact text matching.

• claw-forge status

  tells you exactly what to do next — trust it.

• claw-forge ui

  is the best way to monitor long runs — live logs per agent, cost tracking, dependency graph.
• Provider API keys go in

  .env

  (never commit).

  .env.example

  is the template.