---

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 tick, lease-backed 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.4.26)

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.

Development

npm run build          # TypeScript -> dist/
npm test               # Unit + e2e tests
npm run test:unit      # Unit tests only (359 tests, 59 files)
npm run test:e2e       # E2E tests only (25 tests, 19 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 a mini-host smoke on OpenClaw 2026.4.26: manual init -> plan -> run -> review -> report and live ACP init -> plan -> run -> session status -> session close.

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.