SwarmOps

SwarmOps is version control for swarms of coding agents: many agent processes commit into one repository at once.

Documentation · Install · Quick start · Roadmap · Contributing

SwarmOps is pre-release, at v0.11.0 (2026-11-09). It is designed for large pools of coding agents that commit, land and sync with git. It is measured today at 50 agents landing on one host: 25.0 lands/s, nothing lost (perf.md). The roadmap says what comes next.

Linux x86_64 (tested) and aarch64 (smoke-tested under emulation), glibc 2.34 or newer; no macOS or Windows build yet.

Install

The recommended path:

curl -fsSL https://get.swarmops.cc/install.sh | bash

It installs swarmops and so into ~/.local/bin from the latest release, checked against its SHA256SUMS, and running it again updates.

• .deb and .rpm packages: install guide.
• Pinning a version: install guide.
• Building from source: install guide.

Quick start

A store, a first commit and a read. The commands use so; swarmops runs the same.

so --version
so init ./acme --name acme
printf '%s\n' '[{"path": "hello.txt", "op": "put", "content": {"inline": "hello\n"}}]' > change.json
so --repo ./acme --as agent/worker-1 commit -m "Add hello" --changes change.json --advance main
so --repo ./acme cat main:hello.txt

Output of a 0.11.0 build of stable at 6e9dac27, on a busy host:

swarmops 0.11.0+6e9dac27f0ad5098b91fd2156a7e826c9bc5676a
{"ok":true,"op":"repo_init","api":1,"result":{"repo_id":"e6092c987a444fdf107662f9ec67c1be","name":"acme","store_version":2,"changesets":0,"refs":0},"meta":{"repo":"./acme","elapsed_ms":906,"resolved":{},"auth":"trust"}}
{"ok":true,"op":"commit","api":1,"result":{"changeset":"5d6a7b500a60e85d18f6ffd05d7c62836086a34afd57a1f3d706dca00397692e","root":"df3040af7381e7e412c6a0c5e9ab8b490ab80d92dedad94530d98340ced54a6e","files_changed":1,"blobs_written":1,"advanced":{"name":"main","new":"5d6a7b500a60e85d18f6ffd05d7c62836086a34afd57a1f3d706dca00397692e","already_applied":false},"replayed":false},"meta":{"repo":"./acme","elapsed_ms":267,"resolved":{},"auth":"trust"}}
{"ok":true,"op":"read_file","api":1,"result":{"blob":"464418f5a53907c921906843e6f1f4f984f144067b3bf32d69c1ff4c13627464","size":6,"kind":"file","encoding":"utf8","content":"hello\n","truncated":false},"meta":{"repo":"./acme","elapsed_ms":1,"resolved":{"main":"5d6a7b500a60e85d18f6ffd05d7c62836086a34afd57a1f3d706dca00397692e"},"auth":"trust"}}

Each store command prints one JSON envelope. --advance main moved main to the new changeset in the commit's own transaction. Reads need no identity; a commit, a land, a ref move and an undo need one, from --as or SWARMOPS_AGENT. The quick start guide goes on to a land, a conflict and an undo.

What it does

Many agents commit into one store at once

Each agent process writes the store directly: object writes take no lock, metadata writes queue in the kernel for one flock, which a killed agent never leaves behind, and refs move only by compare-and-swap. Measured (G1, met): 50 processes × 1,000 commits through the binary, 74.0 commits/s, no E_BUSY, no commit lost (perf.md; Parallel agents).

Land with retry and a conflict report

land merges a change three-way onto a ref's head without a checkout and moves the ref in one transaction, merging again and retrying when the ref moves; --key makes a rerun a replay. A conflict records nothing and returns E_CONFLICT with each file's hunks and the agent that last changed it; land --resolve settles it path by path. Measured (G4, met at 50 processes): 25.0 lands/s, p99 157.320 ms and 154.458 ms in two gated runs, no retry, nothing lost; the 32-process runs are owed (perf.md; Commit and land).

One JSON envelope per command, and an MCP server

Every command prints one envelope, ok, op, api, result or error, then meta (exceptions). A failure carries a stable E_* code, the exit code, retryable, details and a hint (error reference). swarmops schema prints the JSON Schema of every request and response, and swarmops mcp serves the operations to an agent as 46 MCP tools (MCP integration).

Git and GitHub round trip

git import brings a git history in; git export writes it back, an imported commit as itself, byte for byte, a store changeset with a SwarmOps-Changeset: trailer. clone, fetch, push and sync reach a git remote such as GitHub through your own git (2.39 or later), pushing by compare-and-swap, never by force. Measured (G17, met): one commit's push on 12,000 commits 1.02× its cost on 1,000 (perf.md; Git round trip, GitHub as a remote).

Workspaces

so ws create writes a changeset's tree, or the paths under --prefix, into a directory where an agent edits, builds and tests. ws land --check commits, rebases, runs the check and publishes only if the target has not moved, so the landed tree is the tested one. An adapter gives Claude Code's worktree hooks a workspace (Build and test a change).

Features runs each, plus the op log and undo, crash safety and verify.

When not to use it

• You need macOS or Windows: SwarmOps builds for Linux only today (both are planned).
• You need git parity: hooks, signing, submodules and LFS are a non-goal.
• Several hosts must write into one store at once: today one host writes and the others sync through a git remote (several writers are planned).
• The store would sit under /mnt/, which is refused with E_UNSUPPORTED_FS, or on NFS, SMB or FUSE, which are not detected yet and not supported (where a store can live).

Non-goals and known limitations list the rest.

SwarmOps and git

SwarmOps works beside git: it imports from git and exports to it, so review, CI and deployment stay in git. Judged from the design and the code, it is ahead by design on the order of writes, stale locks, durability and machine-readable errors, and behind on write throughput, storage on disk, review and ecosystem. No benchmark against git exists. The full comparison, dimension by dimension, is SwarmOps and git.

Documentation

• Install: the installer, packages, a source build.
• Quick start: a store, a commit, a land, an undo.
• Parallel agents: run a swarm on one repository.
• Commit and land: publish a change, retries and conflicts.
• MCP integration: give agents the store as MCP tools.
• Git round trip: import a git repository, export the work back.
• CLI reference: every command, its output and its errors.
• Operating SwarmOps: checks, backup and restore, upgrades, limits.

Every page, by group: docs/README.md.

Roadmap

Each milestone's deliverable and exit criteria are in docs/roadmap.md, under "Milestones"; macOS and Windows builds are planned (M12). CHANGELOG.md says what each release shipped, and docs/known-limitations.md what is still open, with the milestone that takes each item.

Contributing, security and licence

• CONTRIBUTING.md: how changes are made; just check is the definition of done.
• SECURITY.md: how to report a vulnerability privately.
• SUPPORT.md: where to ask a question or report a problem.
• CODE_OF_CONDUCT.md: the conduct expected in every project space.
• LICENSE: MIT. Each release archive also carries THIRD-PARTY-LICENSES, the licences of the crates compiled into swarmops and so.