ProjectGoals
View as MarkdownGoals#
SwarmOps is a version control system, written in Rust, for swarms of coding agents: tens of agent processes on one host committing into one repository at once, every command answering in JSON, and the work going back to git so that CI and deployments run as before. It is built for one host first and then, offline-first, for several. This page states what SwarmOps sets out to do, how each goal is measured, where its target is written down, what has been measured so far, and which milestone delivers it. docs/perf.md holds every measurement, docs/known-limitations.md what is still open, and docs/roadmap.md the milestones, in detail.
Who it is for#
- People who run agent swarms. 10 to 50 Claude Code or LangGraph processes working in one repository on one host, where agents in separate git worktrees serialize nothing and leave the merging to whoever pushes last.
- The agents themselves. A program reads a stable error code, an exit code and whether a retry can help; it does not parse prose. It reaches the store through the CLI or an MCP server.
- Teams that keep git. The store imports a git history and exports the landed work back to git, so a repository's CI, review and deployment keep their source of truth until the team decides otherwise. Planned: the store fetches from and pushes to GitHub itself, and people keep stock git against a store (docs/roadmap.md).
Goals#
"Stated in" names the public document that states the target. "Measured" cites a section of docs/perf.md, or says that no measurement exists yet. The milestones are those of docs/roadmap.md; the order of those from M5 on is settled once the pilot has run.
| # | Goal | Metric | Target | Stated in | Measured | Milestone |
|---|---|---|---|---|---|---|
| G1 | Many writers, one store | Commits by concurrent agent processes; E_BUSY failures | 10 to 50 processes; no E_BUSY (retryable, after the 10 s lock timeout) and no lost commit | README (intro); perf.md, "32 agents committing through the binary" (the plan's "0 failures") | 32 × 1,000 commits: E_BUSY 0, 71.7 commits/s, meta.elapsed_ms p99 621 ms, spread 1.00× ("v0.1.0 — just perf in a quiet window"). 50 processes: not yet measured | M1 (done); a FIFO hand-off on the lock, M6 |
| G2 | Cheap commits | Commit latency, syncs excluded | ≤ 5 ms + 0.3 ms per changed file | perf.md, "M0 fsync latency" and "32 agents committing through the binary"; known-limitations, "Full fsync is slow" | Without syncs: not yet measured. With full fsync: an uncontended commit 19 ms p50; 256 new objects written and synced on 32 threads in 72.9 ms, against the target's 82 ms ("v0.1.0 — just perf in a quiet window"; the 82 ms in "M1 store level") | M2's journal-sync decision, after the pilot |
| G3 | Fast reads | Lookup and snapshot latency | < 1 ms | perf.md, "Index lookups" | Index lookups ≤ 6.13 µs; a snapshot and lookup ≤ 152.9 µs p99 at 100,000 changesets; with 256 refs, 1.55 ms p50 and 3.00 ms p99, over the target ("v0.1.0 — just perf in a quiet window") | M1 (done); the many-refs case is not scheduled yet |
| G4 | Landing under a swarm's load | Lands/s, p99 latency, retry rate, lost lands, at 32 and 50 landing processes | At 50 processes: ≥ 20 lands/s, p99 < 500 ms, retries < 5 %, nothing lost | known-limitations, "Landing retries under a burst"; README, "Roadmap" | Not yet measured. A probe on a loaded host (known-limitations, same entry) landed every change exactly once, with 22 %, 44 % and 44 % of lands retried at 8, 16 and 32 processes | M4's landing measurements and landing model, after the pilot |
| G5 | Durability | Acknowledged commits lost after a crash or a power loss | 0, with full fsync as the only mode | README, "Why SwarmOps"; CONTRIBUTING, "The rules" | Crash sweeps, injected I/O errors and modelled power-loss images pass through the real binary; a literal SIGKILL on a real device is not tested yet (known-limitations, "Durability"). The fsync cost that keeps the default: p99 5.41 ms per durable write ("M0 fsync latency") | M1, M1.5 (done); M6 |
| G6 | An agent contract | Stable E_* codes, exit codes and schema; MCP | Codes, exit codes, the envelope and the schema change only as the versioning policy allows; every code pinned by a golden envelope | docs/policies/versioning-and-stability.md; known-limitations, "Golden envelopes cover 27 of the 37 error codes" | 37 codes, 27 pinned by golden envelopes; JSON Schema for 91 types (architecture.md, "The contract"); MCP server since M1.5 | M1, M1.5 (done); the remaining ten codes are not scheduled yet |
| G7 | A faithful git round trip | Commits missing or rewritten after import, land and export; lossy classes | None missing, rewritten 0, git fsck --strict passes; each of the six lossy classes refused unless --lossy names it | README, "Bring a git repository in" and "Send the work back to git"; docs/pilot.md, "Success criteria" 1 and 4 | Fixtures pass with three git versions every week (CONTRIBUTING, "Continuous integration"); real repositories: not yet measured (known-limitations, "No test reads a real repository yet") | M3, M8 (done); the pilot |
| G8 | Portability | Platforms built, tested and released | macOS and Windows beside Linux | README, "Roadmap"; docs/policies/msrv-and-platforms.md | x86_64 Linux tested; aarch64 Linux smoke-tested under QEMU | M12 |
| G9 | Workspaces | An agent builds and tests a change on disk before it lands it | Sparse workspaces, with an adapter for Claude Code's worktree hooks | README, "Roadmap" | Not built | M5 |
| G10 | Integrity tools | Repair, cleanup and detection | fsck and repair, gc, unsupported-filesystem detection, bounded reads, the next store FORMAT | README, "Roadmap"; known-limitations, "Verification and repair" | Not built; verify --deep checked 128,306 objects in 1,758 ms ("v0.1.0 — just perf in a quiet window") | M6 |
| G11 | Review | Change requests and a landing gate | Blame, change requests, their classification, approvals and a landing gate | README, "Roadmap" and "SwarmOps and git" | Not built | M7 |
| G12 | Simulation and a benchmark gate | Regressions caught before they land | The store under a deterministic simulator and random kills; just bench fails on a regression over 20 % | README, "Roadmap"; perf.md (its first paragraph) | No gate yet (known-limitations, "No benchmark gate") | M9 |
| G13 | Several hosts, offline-first (topology 3: local SwarmOps, remote SwarmOps) | Sync between hosts without an always-on server | A full store on every host; so clone so://…, fetch, push, sync and sync status against one upstream, over ssh; every confirmed land upstream exactly once | README, "Roadmap"; docs/roadmap.md, "Topology 3" | Today through a git remote, one writing host at a time (M8) | M11 |
| G14 | Safety | unsafe, fuzzing, supply chain | No unsafe code; four fuzz targets; cargo deny over every lockfile; workflows pinned and checked | CONTRIBUTING, "The rules"; SECURITY.md | Holds in every just check and in the weekly scheduled run | Every milestone |
| G15 | Works together with GitHub | The three topologies' acceptance criteria (G16, G17, G13) | All pass in CI with git 2.39.5, 2.43.0 and 2.56.0, and topology 2's in an opt-in run against GitHub | docs/roadmap.md, "Goal" | Not yet measured: no topology is served natively; topology 2 runs through a hand-moved bare clone (docs/roadmap.md, "Where we are") | M13, M14, M11 |
| G16 | Topology 1: local git, remote SwarmOps | Stock git's clone, fetch, pull and push against swarmops serve; ids after a round trip; a no-op fetch's cost | Every listed git command passes over ssh and HTTP; the same id at every ref and git fsck --strict clean; a no-op fetch and a clone at most 2× git's own server | docs/roadmap.md, "Topology 1" | Not yet measured; not built | M14 |
| G17 | Topology 2: local SwarmOps, remote GitHub | so clone, fetch, push and sync against a git remote; commits rewritten; CI on GitHub; cost of one new commit | rewritten 0 over any number of round trips; GitHub's push workflow runs unchanged; one commit's fetch or push at most 1.5× as costly on 12,000 commits as on 1,000 | docs/roadmap.md, "Topology 2" | Not yet measured; not built | M13 |
Non-goals#
- A general-purpose git replacement. Parity with git is not a v1 goal: no user hooks, signing, submodules or LFS.
- A cluster. SwarmOps is one program with no daemon and no external database. It does not
scale horizontally, and an always-on RPC server is a follow-up after v1, not a milestone.
The planned
swarmops serve(M14, M11) runs per connection, under ssh or as a CGI program, so it adds no daemon. - Writes without a lock. Object writes take no lock; metadata writes take one, which orders every commit and ref move.
- Speed bought with durability. No fast mode exists unless a measurement in docs/perf.md justifies it.
- A benchmark against git worktrees. It is not on the roadmap; the README's comparison with git is judged from the design and the code.
Engineering principles#
- Rust, with no
unsafe.unsafeis forbidden in every crate of the workspace. - Full fsync by default. A commit returns only once its journal frame is on disk.
- Serde types at the store's edge. Store-facing types carry no filesystem paths, so every operation can later run behind an RPC boundary.
- A fixed hash contract. Byte layouts and the hash recipe never change in place; a new layout gets a new kind or version header.
- Every claim measured. A performance statement cites docs/perf.md, with the host, its load and the date.
- Built from its own specification. New work follows the clean-room policy: design material from third parties reaches the code only as functional requirements in SwarmOps' own words.
How goals change#
A goal's target changes only with a measurement recorded in docs/perf.md that justifies the change, and a line in CHANGELOG.md that says what changed and why. A goal is added or dropped the same way, with the reason in the changelog. A measured value in the table is replaced when a newer run in docs/perf.md supersedes it.
Clean-room development
SwarmOps is built from its own specification. Third-party designs, articles and code may inform what SwarmOps should do; they never supply how it is written.…
Toolchain, MSRV and platforms
rust-toolchain.toml pins Rust 1.99.0 (with rustfmt, clippy and llvm-tools), so every local build and every CI run uses exactly that compiler. The one…