Getting Started with SwarmWeaver

SwarmWeaver runs on Python 3.11+ with zero external runtime dependencies across DAG compilation, file-scope leases, SHA-256 checkpoints, and MCP tools.

Install & run the 10-agent crash demo

v1.1.0

Run locally

git clone https://github.com/codesphere-u/swarmweaver.git
cd swarmweaver && pip install -e .
swarmweaver demo && swarmweaver benchmark

CLI Subcommands

Command	Purpose
`swarmweaver plan [-f FILE] [--json]`	Compile tasks into conflict-free parallel waves and print critical path stats.
`swarmweaver demo [--json]`	Execute the 10-agent refactoring DAG with crash injection and instant SHA-256 resume.
`swarmweaver benchmark [--json]`	Run the 4-part reproducible benchmark (200-task DAG, 50-task locks, 20 crash runs, 15 traps).
`swarmweaver verify-journal PATH [--json]`	Audit every `prev_hash -> entry_hash` SHA-256 link in a checkpoint JSONL file.
`swarmweaver mcp`	Start the JSON-RPC 2.0 Stdio MCP server (`2024-11-05`).
`swarmweaver serve-http [--port 8000]`	Launch the Streamable HTTP/SSE MCP server, REST API, Prometheus metrics, and Web UI.

Python SDK

Import SwarmOrchestrator, TaskSpec, and CheckpointJournal directly to schedule parallel Python or LLM agent tasks.

SwarmOrchestrator & TaskSpec

from swarmweaver import SwarmOrchestrator, TaskSpec

tasks = [
    TaskSpec("audit", "Scan AST", read_globs=["src/**/*.py"], output_contract=["inv:dict"]),
    TaskSpec("jwt", "Fix JWT", depends_on=["audit"], write_globs=["src/auth/jwt.py"], input_contract=["inv:dict"]),
    TaskSpec("rbac", "Add RBAC", depends_on=["audit"], read_globs=["src/auth/jwt.py"], write_globs=["src/auth/jwt.py"]),
]

report = SwarmOrchestrator(tasks, journal_path=".swarmweaver/checkpoint.jsonl").run()
print(report.total_waves, report.conflicts_auto_split, report.tokens_saved_by_replay)

CheckpointJournal Integrity

Each completed task appends a canonical JSON record chaining prev_hash -> entry_hash. Call CheckpointJournal(path).verify_integrity() before resuming untrusted disks.

MCP Integration

Connect Claude Desktop, Cursor, or any JSON-RPC 2.0 MCP host to compile waves and audit journals without leaving your editor.

Tools & Resources

swarmweaver_plan_waves — Compile candidate TaskSpec objects into parallel waves and critical-path metrics.
swarmweaver_check_file_conflicts — Test a parallel task batch for write/write or read/write glob intersections.
swarmweaver_inspect_checkpoint — Verify journal hash integrity and list resumable completed nodes.
swarmweaver_run_benchmark — Execute the full 4-axis benchmark suite and return JSON telemetry.
Resources: swarmweaver://workflow/demo-10-agent, swarmweaver://benchmark/summary, swarmweaver://dag/lease-conflict-rules.

MCP Prompts

SwarmWeaver exposes plan-safe-swarm, resolve-file-lease-conflict, and recover-crashed-workflow prompt templates via prompts/list.

HTTP Portal & CI

Serve Streamable MCP, REST endpoints, Prometheus metrics, and the built-in browser DAG Workbench from one zero-dependency HTTP server.

REST & Streamable MCP Endpoints

GET /health, GET /healthz, GET /readyz, GET /info
GET /metrics (Prometheus exposition or ?format=json)
POST /mcp & GET /mcp (Streamable HTTP JSON-RPC 2.0 and SSE)
POST /api/plan, POST /api/conflicts, GET|POST /api/demo, GET|POST /api/benchmark

CI Quality Gate

ruff check .
mypy swarmweaver api scripts
pytest -v --cov=swarmweaver --cov-fail-under=90
python3 scripts/smoke_test.py