Page kind: Start
SwarmOps documentation#
SwarmOps is version control designed for large pools of coding agents: their processes commit into one store at once, every command answers in one JSON envelope, and the work goes back to git.
It is measured today at 50 agents landing on one host: 25.0 lands/s, nothing lost (perf.md, "D2-8 gated runs — 2026-11-09").
Start here#
- Install it: Install SwarmOps on Linux: one command, a package, or a build from source.
- Make a first commit: Quick start: a store, a commit, a land and an undo.
- Run a swarm: Parallel agents: many agents on one repository, beside git worktrees.
- Bring a git repository in: Git round trip: import, land, and export back for CI.
- Look something up: CLI reference: every command, its arguments, its output and its errors.
- Keep a store healthy: Verify and repair: check a store, read what it finds, repair it.
How these pages are organised#
Start pages (Install first) take you from nothing to a store with work in it. Guides (Commit and land first) walk through one task with runs you can repeat. The concept page (Concepts) defines each noun once, from the store to the workspace. Reference pages (CLI reference first) are generated from the code: commands, errors, limits, types and tools. Operate pages (Operating SwarmOps first) are for whoever runs SwarmOps for a swarm on one host. Design pages (Goals first) say what SwarmOps sets out to do, what is measured and what is still open.
What SwarmOps does not do#
Goals, Non-goals lists what SwarmOps does not set out to be: among them a general-purpose replacement of git, a cluster, and writes without a lock. Known limitations lists what is still open, and which milestone takes each item.
All pages#
Start#
| Page | Read it to |
|---|---|
| Install | Install swarmops and so with the installer, a package, 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, an envelope and a workspace are. |
Guides#
| Page | Read it to |
|---|---|
| Commit and land | Publish a change: commits, compare-and-swap, landing, retries and conflicts. |
| Parallel agents | Run many agents on one repository, and see how that compares with agents in git worktrees. |
| History and undo | Read history and diffs, and take an operation back. |
| Git round trip | Import a git repository, and export the work back for review and CI. |
| GitHub as a remote | Clone, fetch, push and sync with GitHub; pull requests, tokens in CI, commit authors, a sync that stops. |
| A store as a remote | Clone, fetch, push and sync another store that swarmops serve serves; what crosses between stores and what stays. |
| Claude Code | Give Claude Code agents the store through MCP. |
Develop#
| Page | Read it to |
|---|---|
| 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. |
| For agents and programs | Find the pages as Markdown, and know what a program may rely on. |
| Code style | How the Google Rust style guide is kept here: what the gate enforces, what review reads for, the recorded deviations. |
Operate#
| Page | Read it to |
|---|---|
| Operations | Find the task page for running SwarmOps for a swarm. |
| Stores | Create a store, place it on a supported filesystem, and set identities. |
| Install and upgrade | Install, upgrade and remove SwarmOps on a host. |
| 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. |
| Monitoring | Know what to watch on a running store. |
| Limits | Know the limits a store and a request enforce. |
| Making room | See what a store keeps and how to free space. |
| Backup and restore | Back a store up and bring it back. |
| Verify and repair | Check a store and act on what the check finds. |
| Serve over ssh | Let people and CI clone, fetch and push a store with stock git over ssh. |
| Serve over HTTP | Serve the same store over HTTPS, through a web server. |
| Where serve differs from git | See each place where swarmops serve answers stock git differently from git's server. |
| Troubleshooting | Go from a symptom to its cause and the command that fixes it. |
Reference#
| Page | 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. |
| Coming from git | Look up a git command, what to type instead and the hint a refusal carries. |
Project#
| Page | Read it to |
|---|---|
| Goals | See what SwarmOps sets out to do: each goal with its metric, target, measured value and milestone. |
| Roadmap | See where SwarmOps is going: the milestones, built and planned, and working with GitHub in three topologies. |
| 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. |
| Pilot | Follow the runbook of the first real use, on this repository. |
| Changelog | See what changed, release by release. |
| 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. |
| Clean-room development | See how third-party designs reach the code: requirements only, with provenance and checks. |
| SwarmOps and git | Compare SwarmOps with git, dimension by dimension. |
| Metadata store comparison | See how the native metadata store is measured against embedded databases. |
| Support | Find where to ask a question or report a problem. |
| Security | Report a vulnerability privately, and learn what counts as one. |
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.