claw-forge CLI

---

name: claw-forge-cli

description: >

Use the claw-forge CLI to run autonomous coding agents on a project until all

features pass. Covers the full workflow: init → spec → plan → run → status →

ui. Use when a user asks to build a project with claw-forge, run agents on a

codebase, generate a feature DAG, manage the provider pool, or fix bugs with

the reproduce-first protocol.

repo: https://github.com/clawinfra/claw-forge-cli-skill

metadata:

{

"openclaw": {

"requires": { "bins": ["claw-forge"] },

"install": [

{

"id": "pip",

"kind": "pip",

"package": "claw-forge",

"bins": ["claw-forge"],

"label": "Install claw-forge (pip)"

}

]

}

}

---

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

2 — Write a spec

Create `app_spec.txt` (plain text) or `app_spec.xml` (structured 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

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

Shows real-time agent activity, feature status, costs, and logs.

---

All Commands

| Command | Purpose |

|---------|---------|

| `init` | Bootstrap project (CLAUDE.md, config, slash commands) |

| `plan <spec>` | Parse spec → feature DAG in state DB |

| `run` | Run agents until all features pass |

| `status` | Show progress and recommended next action |

| `ui` | Launch Kanban UI at localhost:8888 |

| `dev` | Start API + Vite dev server (for UI development) |

| `add <spec>` | Add features to an existing project (brownfield) |

| `pause` | Drain mode: finish in-flight, start no new agents |

| `resume` | Resume after pause |

| `fix <desc>` | Fix a bug using RED→GREEN reproduce-first protocol |

| `merge` | Squash-merge a feature branch to target |

| `input` | Answer pending human-input questions interactively |

| `pool-status` | Show provider pool health and current routing |

| `state` | Start the AgentStateService REST + WebSocket API |

---

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