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.

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 (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

• 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.
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

• 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.