---

Features

• Spec-driven planning — Markdown spec with goals and phased tasks → dependency-ordered task graph
• ACP-first execution — ACP is the only default-capable automated runner; capability-aware auto resolution
• Supervised autopilot — Deterministic control-plane ticks, optional watcher-driven service loop, and operator-visible start/pause/resume/stop controls
• Persistent sessions — Reuse, thread binding, follow-up, steer, cancel, and close flows
• Review gates — Explicit approve/reject with structured quality rubrics (weighted multi-dimension scoring)
• Sprint contracts — Verifiable acceptance criteria per task with GAN-inspired evaluator injection
• Cross-session continuity — Progress synthesis, bootstrap startup sequence, harness assumption tracking
• Automatic retry — Configurable per-task retry policy with dead letter tracking and signal-based auto-retry
• Concurrency protection — ACP session concurrency limits with queued task scheduling (FIFO)
• Reject-retry workflow — Review rejections return tasks to ready for re-run; configurable retry limits
• Parallel dispatch — --parallel N and --all-ready batch dispatch with concurrency-aware slot management
• Operator reporting — Status snapshots, run/review logs, spec archives, completion summaries → local + Obsidian sync
• Runtime diagnostics — swarm doctor, swarm status, and workflow reports surface ACP bridge-exit gate directly

Prerequisites

• Node.js >= 22
• OpenClaw >= 2026.3.22 (tested against 2026.5.3-1)

Installation

From ClawHub (recommended)

openclaw plugins install clawhub:openclaw-swarm-layer

Skill From ClawHub

openclaw skills install swarm-layer

From npm

npm install -g openclaw-swarm-layer
openclaw plugins install openclaw-swarm-layer

From source

git clone https://github.com/xucheng/openclaw-swarm-layer.git
cd openclaw-swarm-layer
npm install && npm run build
openclaw plugins install -l /path/to/openclaw-swarm-layer

Quick Start

# 1. Initialize a project
openclaw swarm init --project /path/to/your/project

# 2. Import a spec and build the workflow
openclaw swarm plan --project /path/to/your/project --spec SPEC.md

# 3. Inspect runtime posture before execution
openclaw swarm doctor --json
openclaw swarm status --project /path/to/your/project --json

# 4. Dry-run with the resolved default runner
openclaw swarm run --project /path/to/your/project --dry-run --json

# 5. Execute
openclaw swarm run --project /path/to/your/project --json

# 6. Review and report
openclaw swarm review --project /path/to/your/project --task <taskId> --approve --json
openclaw swarm report --project /path/to/your/project --json

CLI Commands

Core Workflow

Command	Description
swarm init --project <path>	Initialize swarm state for a project
swarm plan --project <path> --spec <path>	Import a spec and build task graph
swarm run --project <path> [--runner acp|manual] [--dry-run] [--parallel N] [--all-ready]	Execute runnable tasks (single or batch)
swarm review --project <path> --task <id> --approve|--reject [--retry-now]	Approve or reject a task
swarm report --project <path>	Generate a workflow report
swarm status --project <path>	Show workflow status, runtime posture, and bridge-exit gate
swarm doctor	Diagnose ACP readiness and bridge-exit gate status
swarm autopilot status --project <path>	Inspect autopilot health, lease state, and last decision
swarm autopilot start/pause/resume/stop --project <path>	Control the supervised autopilot service state
swarm autopilot tick --project <path> [--dry-run]	Sync active runs, review state, and queue pressure through the supervised control plane

Session Management

Command	Description
swarm session list --project <path>	List known sessions
swarm session inspect --project <path> --session <id>	Inspect a session
swarm session status --project <path> --run <id>	Poll session status
swarm session cancel --project <path> --run <id>	Cancel an active session
swarm session close --project <path> --run <id>	Close a session
swarm session follow-up --project <path> --session <id> --task <desc>	Inject a follow-up task
swarm session steer --project <path> --session <id> --message <text>	Send a steering message
swarm session cleanup --project <path> [--stale-minutes <n>]	Clean up orphaned sessions

Runner Model

Runner	Role	Default-capable	Requirements
acp	Primary automation path	Yes	ACP enabled, public control-plane available
manual	Operator-driven safe fallback	Always available	None

defaultRunner: "auto" resolves to acp when ACP automation is available, otherwise falls back to manual.

Autopilot Watcher Mode

Autopilot defaults to the existing polling loop. Version 0.5.4 adds optional filesystem watcher modes that can drive ticks from workflow-state changes while keeping polling as the rollback path.

{
  "autopilot": {
    "enabled": true,
    "watcherMode": "hybrid",
    "watcher": {
      "debounceMs": 100,
      "safetyTickMs": 300000,
      "library": "auto"
    }
  }
}

Use watcherMode: "watch" for event-driven operation, hybrid for watcher events plus low-frequency safety polling, and polling to return to the pre-0.5.4 behavior.

Development

npm run build          # TypeScript -> dist/
npm test               # Unit + e2e tests
npm run test:unit      # Unit tests only (421 tests, 62 files)
npm run test:e2e       # E2E tests only (26 tests, 20 files)
npm run test:watch     # Watch mode
npm run release:check  # Build + full regression + npm pack dry-run + ClawHub package prep

Current release validation also includes OpenClaw 2026.5.3-1 smoke coverage on local and remote staging environments: plugin load, manifest contracts, openclaw-swarm-layer doctor checks, runtime health, and node/parcel autopilot watcher smoke.

Documentation

User Guides:

• User Manual — Install, configuration, daily workflow, and troubleshooting
• Configuration Reference — Config schema, defaults, examples, and journaling
• Skills Guide — Unified skill usage modules
• Release Runbook — npm, GitHub release, ClawHub package, and ClawHub skill publishing steps

Operations:

• ACP Bridge Exit Gate — Bridge-free ACP floor, live smoke matrix, artifact expectations
• Operator Runbook — Install, smoke, upgrade, rollback, and ACP control-plane operations
• Migration Checklist — Staged bridge replacement planning
• Testing Strategy — Unit, e2e, and smoke verification rules

Project History:

• Changelog — Release notes
• Roadmap — Milestone structure and delivery history
• Milestones — Definition of done per milestone

License

MIT

Contributing

See CONTRIBUTING.md.