ClawForge

   ________                ______
  / ____/ /___ __      __ / ____/___  _________ ____
 / /   / / __ `/ | /| / // /_  / __ \/ ___/ __ `/ _ \
/ /___/ / /_/ /| |/ |/ // __/ / /_/ / /  / /_/ /  __/
\____/_/\__,_/ |__/|__//_/    \____/_/   \__, /\___/
                                         /____/

Forge and manage fleets of OpenClaw agents.

Build agents, shape their identity, wire them to channels, deploy fleets — then run coding workflows or anything else.

Inspired By

This project was inspired by Elvis's "OpenClaw + Codex/Claude Code Agent Swarm" workflow — a battle-tested system for managing a fleet of AI coding agents.

Quick Start

# 1. Create an agent from a template
clawforge create scout --from monitor --name Scout --role "External monitoring"

# 2. Bind it to a Discord channel
clawforge bind scout "#scout"

# 3. Activate — adds to config and restarts gateway
clawforge activate scout

# Check your fleet
clawforge list

Fleet Commands

The primary interface. Everything starts here.

| Command | Description | |---------|-------------| | clawforge create <id> | Interactive agent creation wizard | | clawforge create <id> --from <archetype> | Create from template (non-interactive) | | clawforge list | Fleet overview — all agents with status | | clawforge inspect <id> | Deep view: config, workspace, bindings | | clawforge edit <id> --soul\|--agents\|--tools\|--heartbeat | Edit workspace files | | clawforge bind <id> <channel> | Wire agent to Discord/Telegram/etc | | clawforge unbind <id> | Remove channel binding | | clawforge clone <source> <new-id> | Duplicate an agent | | clawforge activate <id> | Add to config + restart gateway | | clawforge deactivate <id> | Remove from config (keep files) | | clawforge destroy <id> | Full removal (requires --yes) | | clawforge export <id> | Package as shareable .clawforge archive | | clawforge import <path\|url> | Import from archive | | clawforge migrate | Workspace isolation migration | | clawforge apply | Alias for activate | | clawforge doctor | Fleet + system health check | | clawforge compat | Fleet-wide model/tool compatibility (via clwatch) | | clawforge upgrade-check | Tool update recommendations (via clwatch) |

clawforge list — Fleet Overview

🔨 ClawForge Fleet — 4 agents

 ID          Name        Model              Channel      Status
 ────────────────────────────────────────────────────────────────
 main        Claw        gpt-5.4            #claw        ● active
 builder     Builder     gpt-5.4            #builder     ● active
 researcher  Researcher  gpt-5.4            #researcher  ● active
 scout       Scout       gpt-5.4            —            ○ created

 ● = active   ○ = created (not yet bound/activated)   ◌ = config-only

clawforge inspect <id> — Agent DNA

🔧 Builder

 Config
 ──────────────────────────────────
 ID:          builder
 Model:       openai-codex/gpt-5.4
 Workspace:   ~/.openclaw/agents/builder/
 Channel:     discord #builder

 Workspace Files
 ──────────────────────────────────
 SOUL.md          3.7 KB  ✓  Coding specialist, direct and practical
 AGENTS.md        3.5 KB  ✓  Boot sequence with dispatch patterns
 HEARTBEAT.md     168 B   ○  Empty

Templates & Archetypes

ClawForge ships five built-in archetypes. Use them as starting points:

| Archetype | Best For | |-----------|----------| | generalist | All-purpose, can orchestrate other agents | | coder | Code-focused, knows Claude Code / Codex dispatch patterns | | monitor | System/external monitoring with periodic health checks | | researcher | Deep research, synthesis, source citation | | communicator | Multi-channel messaging, notification routing |

# Create from built-in archetype
clawforge create ops --from generalist

# Preview an archetype
clawforge template show coder

# Save an existing agent as a reusable template
clawforge template create my-coder-v2 --from builder

# List all templates (built-in + yours)
clawforge template list

# Delete a user template
clawforge template delete my-coder-v2

User templates live at ~/.clawforge/templates/.
Built-in archetypes live at config/archetypes/ in the ClawForge install dir.

Export & Import (Agent Sharing)

Share agents with your team or across machines.

# Package an agent (skips memory and USER.md by default)
clawforge export builder
# → builder.clawforge in current directory

# Include memory files
clawforge export builder --with-memory

# Skip USER.md (private info)
clawforge export builder --no-user

# Custom output path
clawforge export builder --output ~/share/builder-v2.clawforge

# Import from file
clawforge import builder.clawforge

# Import from URL
clawforge import https://example.com/releases/coder.clawforge

# Non-interactive import
clawforge import coder.clawforge --id my-coder --model anthropic/claude-sonnet-4-6

What's in an archive

builder.clawforge (tar.gz)
├── manifest.json   # agent id, name, model, archetype, dates, clawforge version
├── SOUL.md
├── AGENTS.md
├── TOOLS.md
├── IDENTITY.md
├── HEARTBEAT.md
└── references/     # optional context docs

Import creates workspace at ~/.openclaw/agents/<id>/, prompts for ID and model, then shows next steps.

clwatch Integration

When clwatch is installed, ClawForge gets richer:

# Fleet-wide model/tool compatibility check
clawforge compat

# Check for tool updates + fleet impact
clawforge upgrade-check

# Expanded doctor with tool version info
clawforge doctor

# Auto-patch agent reference files when tools update
clawforge changelog check --auto
clawforge changelog watch             # daemon: polls every 6h

Fleet Compatibility Report
────────────────────────────────────
 Agent       Model        Harness Compat    Deprecations
 main        gpt-5.4      codex ✓           none
 builder     gpt-5.4      codex ✓ claude ✓  none

ClawForge works fully without clwatch. Install it to add compatibility checking, deprecation warnings, and auto-patching.

brew install cyperx84/tap/clwatch

Legacy Coding Workflows

The original ClawForge sprint/review/swarm workflows are still available, now under the coding namespace.

# Preferred (v2.0+)
clawforge coding sprint "Add JWT authentication"
clawforge coding review --pr 42
clawforge coding swarm "Migrate tests from jest to vitest"

# Bare forms still work — deprecated, removed in v3.0
clawforge sprint "Add JWT authentication"
clawforge review --pr 42
clawforge swarm "Migrate tests"

Coding commands quick reference

| Command | Description | Key Flags | |---------|-------------|-----------| | coding sprint | Single agent, full dev cycle | --quick, --branch, --agent, --auto-merge | | coding review | Quality gate on PR (analysis only) | --pr, --fix, --reviewers | | coding swarm | Parallel multi-agent orchestration | --max-agents, --repos, --auto-merge | | coding steer | Course-correct a running agent | (task ID, message) | | coding attach | Attach to agent's tmux session | (task ID) | | coding stop | Stop a running agent | --yes, --clean |

Full docs: docs/workflow-modes.md

Installation

| Method | Command | Best For | |--------|---------|----------| | Homebrew | brew install cyperx84/tap/clawforge | macOS users (recommended) | | npm | npm install -g @cyperx84/clawforge | Node.js users | | uv | uv tool install clawforge | Python users | | bun | bun install -g @cyperx84/clawforge | Bun users | | Source | See below | Development |

Homebrew (recommended for macOS)

brew tap cyperx84/tap
brew install cyperx84/tap/clawforge

Upgrade later:

brew update && brew upgrade clawforge

npm / bun

npm install -g @cyperx84/clawforge
# or
bun install -g @cyperx84/clawforge

uv (Python)

uv tool install clawforge
uv tool upgrade clawforge   # upgrade

Source install

git clone https://github.com/cyperx84/clawforge.git
cd clawforge
./install.sh --openclaw

That command will:

• symlink clawforge into ~/.local/bin
• wire up SKILL.md for OpenClaw
• create missing directories if needed

Manual install

mkdir -p ~/.local/bin
ln -sf "$(pwd)/bin/clawforge" ~/.local/bin/clawforge

# Optional OpenClaw skill wiring
mkdir -p ~/.openclaw/skills/clawforge/scripts
ln -sf "$(pwd)/SKILL.md" ~/.openclaw/skills/clawforge/SKILL.md
ln -sf "$(pwd)/bin/clawforge" ~/.openclaw/skills/clawforge/scripts/clawforge

Prerequisites

• bash 4+, jq, git, tmux
• gh (GitHub CLI, authenticated) — for coding workflow commands
• claude and/or codex CLI — for coding workflow commands

Configuration

config/defaults.json:

{
  "fleet": {
    "workspace_root": "~/.openclaw/agents",
    "template_dir": "~/.clawforge/templates",
    "default_model": "openai-codex/gpt-5.4",
    "default_archetype": "generalist"
  },
  "clwatch": {
    "auto_check": true,
    "warn_on_deprecations": true,
    "compat_check_on_create": true
  },
  "default_agent": "claude",
  "default_model_claude": "claude-sonnet-4-5",
  "default_model_codex": "gpt-5.3-codex",
  "ci_retry_limit": 2
}

Documentation

Full docs in docs/:

• Fleet Management
• Archetypes Reference
• clwatch Integration
• Coding Workflows
• Migration Guide
• Command Reference
• Dashboard (Go TUI)
• Architecture
• Configuration
• Troubleshooting
• Changelog

Testing

./tests/run-all-tests.sh

# Phase 3 specific
./tests/test-fleet-phase3.sh