Reef

Reef

Version control for fleets of coding agents.

Reef keeps git's content-addressed storage and replaces git's working model with one suited to many concurrent, speculative, token-constrained authors. The name is the metaphor: a durable structure built by countless small organisms.

Status: Phase 1 (leased copy-on-write workspaces) is complete and was released as 0.1.0 (2026-10-25). Phase 2 (typed API, MCP server, and live state) is complete and was released as 0.4.0 (2026-11-03); the latest release is 0.4.2, with prebuilt binaries for macOS and Linux and Python and TypeScript SDKs. Start with the quickstart. The CLI is not stable yet. The work is tracked in docs/dev-tickets; see What runs today and the roadmap below.

Why

Git was designed for a few dozen humans making a few commits a day. Agents break every assumption behind that design.

• Commit volume rises by orders of magnitude. Thousands of small changes a day from dozens of concurrent writers. Anything that costs O(repository size) becomes the bottleneck.
• Most work is speculative. An agent tries several approaches and keeps one. Branching, snapshotting, and discarding must be nearly free.
• The consumer of history is also an agent. Tokens are a performance metric. A diff that costs 40k tokens to read is slow no matter how fast it computed.
• Conflicts are routine. Two agents editing the same file at once is the normal case. A conflict that halts an agent in a modal state halts the fleet.
• Trust shifts from author to evidence. No human can review every line. A change must carry verifiable evidence of which tests ran on exactly this tree.
• Git ceremony is waste. Staging areas, detached HEADs, and parsing porcelain output burn tokens and cause errors. Agents want a typed API.

Git worktrees, the current answer to agent isolation, make the problem concrete: every worktree is a full copy, its dependency directories dwarf the source, it has no owner and no expiry, and it holds the only copy of uncommitted work, so nobody dares delete one.

What Reef does differently

1. Snapshots, not commits. The working copy is always a snapshot. No staging area, no uncommitted state.
2. Stable identity, mutable content. A change has a permanent ID that survives rebase and amendment.
3. Conflicts are first-class objects. A conflicted merge still produces a valid snapshot. It can be stored, delegated to a resolver, or fixed later. Nothing blocks.
4. Everything is undoable. A global operation log records every mutation, so any agent action reverts in one call (reef undo ).
5. Workspaces are caches, not truth. Working directories are leased, copy-on-write, and reclaim themselves when the agent goes away. Deleting one loses nothing.
6. Hub and ephemeral workspaces. One authoritative store per repository with lazy-fetching clients. Full clones are the exception.
7. Evidence rides with the change. Test results and build hashes are signed, content-addressed objects linked to the snapshot they were computed on. Landing is gated on evidence, not on who pushed.
8. API first, CLI second. A local daemon speaks a typed protocol. The CLI and an MCP server are thin clients. No agent should ever regex a log.

A proposal is the unit of review: a change or stack of changes, with its evidence, put forward for main. It is the change itself in its proposed state, identified by its change ID. There are no pull requests.

What runs today

Reef works on existing git and Jujutsu repositories. Release 0.1.0 was Phase 1, which replaces git worktrees for agents, and 0.2.0 to 0.4.0 add Phase 2. Coming from 0.3, read Upgrading from 0.3; from 0.2, Upgrading from 0.2 as well, and from 0.1, Upgrading from 0.1 too.

Phase 1 (0.1.0)

• A local daemon (reef daemon run|start|stop|status) serving gRPC over a Unix socket, with its state, configuration, and logs under a per-user state directory. It serves many repositories; the first reef command in a checkout registers it, and in a plain git checkout first creates jj's side of a colocated repository (.jj/ plus one line in .git/info/exclude).
• Leased workspaces. reef ws create materializes a workspace on a change in a second or two on a 100k-file repository (under half a second on overlayfs), reef ws run runs a command inside a fresh workspace with the lease heartbeated for the life of the process and the workspace released on exit, reef ws move puts another change in a workspace's directory without giving up its lease, and reef ws list|inspect|release manage them. When an agent dies, its lease expires, a final snapshot lands in the store, and the directory is reclaimed. Nothing is lost.
• Copy-on-write backends. APFS clones on macOS, kernel overlayfs or fuse-overlayfs on Linux, reflink clones on btrfs and XFS, and a plain copy fallback everywhere, all behind one Backend trait and one conformance suite. A workspace costs disk proportional to what the agent changed.
• Continuous snapshots. A filesystem watcher (notify, or Watchman on large repositories) snapshots each workspace through jj-lib after every debounced write. Watcher snapshots are marked local-only and never leave the machine until a change is published.
• Garbage collection. reef ws gc reclaims operations past the undo window, base cache entries no workspace uses, and stale workspace records, and reports what it freed.
• Backup and restore. reef backup copies the daemon's database and every repository's jj state while agents keep writing, pausing each repository only while its operation files are copied; reef restore brings it back offline, and the next start rebuilds every workspace's directory from its last snapshot without reclaiming any (ADR 0020). A quiesce RPC holds the daemon still for a filesystem snapshot instead.
• Shared dependency stores. A reef.toml in the repository declares stores such as node_modules or target; reef store build builds one in a scratch workspace and seals it, and the daemon mounts it read-only into every workspace after verifying it against the lockfile hash.
• A CLI an agent can learn from. reef alone prints a one-screen guide, reef here says which workspace you are in and what to run next, every error with a known fix carries it as a hint and a next command, and no command ever waits on input (ADR 0025).
• Benchmarks for snapshot cost and workspace creation on synthetic repositories of 1k to 100k files, published from CI on both platforms. See docs/benchmarks.md for the numbers against the Phase 1 exit criteria.
• An onboarding benchmark. A real Claude Code agent that has never seen Reef, given only reef on PATH, after reef init, with Reef not yet installed, and inside reef ws run: tool calls, failed reef calls, tokens, and cost to a working workspace, three trials each, run in CI on demand. See docs/onboarding-benchmark.md.

Phase 2 (0.2.0 to 0.4.0)

• A typed API and a thin CLI. The daemon serves reef.api.v1, a versioned protobuf schema checked by buf lint and breaking-change checks in CI (ADR 0029). The reef binary is a client of it with no jj-lib of its own (ADR 0033).
• Changes without jj. reef status, log, show, diff, describe, abandon, undo, op log, op show, ws snapshot, file read and file list look at and revert what agents did, from a workspace or the checkout, with JSON for each and a next command on every error with a known fix (ADR 0034). The API also reads files, lists directories, and applies edits at any revision without a workspace directory (ADR 0032).
• An MCP server. reef mcp serves the API to an agent harness over stdio as twenty-one tools named after its RPCs: workspaces, status, the log, changes, diff, files (read, list and edit, without a directory), describe, abandon, the operation log, undo, which changes touched a file or symbol, and a tool that waits for other agents' operations. reef init writes its entry for Claude Code, Codex and opencode (ADR 0035).
• Live operations. SubscribeOperations streams the operation log as operations are recorded, filtered by repository, change, workspace, or agent, and resumes from a cursor; reef op watch prints it (ADR 0036). A broker reads each operation once and fans it out (ADR 0038): with 500 subscribers at 1,000 operations a minute, p99 delivery is 53 ms for operations and 57 ms for presence on a 12-core Mac (docs/load-tests.md).
• Presence. What each agent is doing now: its activity, the files it is editing, lease heartbeats, and the progress of workspace creates and store builds, never persisted (ADR 0037). reef ws run and reef mcp report it on their own, reef presence report and clear report finer activity, reef presence watch shows it, and reef ws renew renews a lease held outside ws run.
• A symbol index. The daemon extracts definitions and references with tree-sitter for Python, TypeScript and JavaScript, Go, and Rust, in the background for new snapshots and edits, and accepts uploaded SCIP indexes; reef symbols index, upload and list drive it (ADR 0042).
• Symbol-level diffs and history. reef diff --symbols says which definitions a change added, removed, changed or moved, and which call sites they affect (ADR 0043). reef history and the MCP query_changes tool answer which changes touched a file or a symbol, by whom, and how each ended: open, landed, abandoned or undone (ADR 0044).
• Output sized for agents. Piped output is brief JSON with only the keys an agent acts on (ADR 0045), and reef --help is a 509-byte task-first help (ADR 0051): in live Claude Code runs on the CLI, answering "what is the state of this repo" took a seventh of the tokens git did (docs/token-benchmark.md). reef schema prints the commands, MCP tools and API as JSON Schema, for generating tool definitions.
• One-line installs for agents. A Claude Code plugin and a Codex plugin from this repository, reef init --agents opencode --user, and the MCP server on the MCP registry (ADR 0052). A harness that isolates sessions in git worktrees can ask Reef for workspaces instead, through the workspace provider contract; Claude Code's comes as the opt-in reef-workspaces plugin (ADR 0053).
• Status without a tree walk. The watcher keeps an index of what changed, so status on a 100,000-file workspace takes 12 ms when nothing changed, against 161 ms for a walk (ADR 0048).
• Remote access. A daemon in a VM serves the same API and web UI to another machine over TLS with a scoped, revocable token (ADR 0049).
• A local web UI. `reef