SwarmOps documentation#

The documents, grouped by what you want to do. The README shows the core features, each with an example.

Get started#

Document	Read it to
Install	Install `swarmops` and `so` with the installer, from a release archive or from source; upgrade or remove them.
Quick start	Make a store, commit, land a change, meet a conflict and read the op log.
Concepts	Learn what a store, a revision, a change list, a ref, a land and an envelope are.

Use#

Document	Read it to
Commit and land	Publish a change: commits, compare-and-swap, landing, retries and conflicts.
History and undo	Read history and diffs, and take an operation back.
Parallel agents	Run many agents on one repository, and see how that compares with agents in git worktrees.
Claude Code	Give Claude Code agents the store through MCP.
Git round trip	Import a git repository, and export the work back for review and CI.
MCP integration	Connect any MCP client: registration, the stdio exchange, identity, every tool and its command, limits and failures.
CLI scripting	Drive SwarmOps from scripts: the envelope, exit codes, jq recipes, retries and idempotency keys.

Operate#

Document	Read it to
Operations	Find the task page for running SwarmOps for a swarm.
Install and upgrade	Install, upgrade and remove SwarmOps on a host.
Stores	Create a store, place it on a supported filesystem, and set identities.
Agents	Give agents the store through MCP.
The daily loop	Move work between the store and git every day.
Build and test	Build and test a change on disk before it lands.
One writer per trunk	Keep one writer on the git side of each trunk.
Verify and repair	Check a store and act on what the check finds.
Backup and restore	Back a store up and bring it back.
Making room	See what a store keeps and how to free space.
Monitoring	Know what to watch on a running store.
Limits	Know the limits a store and a request enforce.
Troubleshooting	Go from a symptom to its cause and the command that fixes it.
Pilot	Follow the runbook of the first real use, on this repository.
Support	Find where to ask a question or report a problem.
Security	Report a vulnerability privately, and learn what counts as one.

Reference#

Document	Read it to
CLI reference	Look up a command, its arguments and its output.
Error reference	Look up an `E_*` code, its exit code and what to do.
Limits	Look up a limit, its value, constant, commands and error.
Schema types	Look up a request, response or value type and its fields.
MCP tool reference	Look up an MCP tool, its input schema, annotations, an example call and its CLI command.
Versioning and stability	Know what stays compatible, and how a breaking change is made.
MSRV and platforms	Know the Rust version and the platforms SwarmOps supports.
Changelog	See what changed, release by release.

Design#

Document	Read it to
Roadmap	See where SwarmOps is going: working with GitHub in three topologies, each with its commands, design, acceptance criteria and milestone.
Goals	See what SwarmOps sets out to do: each goal with its metric, target, measured value and milestone.
Clean-room development	See how third-party designs reach the code: requirements only, with provenance and checks.
Architecture	Understand the design: crates, data model, the store on disk, the write and read paths, durability, concurrency, the contract.
Known limitations	See what is still open, and which milestone takes each item.
Performance	See every measurement, and the decisions taken on them.
Metadata store comparison	See how the native metadata store is measured against embedded databases.
SwarmOps and git	Compare SwarmOps with git, dimension by dimension.
Roadmap	See the milestones, built and planned.

The design documents are the authority: the umbrella spec and the storage, operations and review specs, in Korean, which the maintainers keep privately; Architecture is their public overview. How changes are made is in CONTRIBUTING.md, who makes them in MAINTAINERS.md, and how a release is cut in RELEASE.md.