Reef MCP server
Commit Nov 14, 2026Provides version control for fleets of coding agents using isolated workspaces, snapshots, and a typed API.
Also known as reef-vcs/reef
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.4.2
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is Reef MCP?
Reef provides version control for fleets of coding agents using isolated workspaces, snapshots, and a typed API.
Summary generated from the project's README
About Reef MCP server
Reef provides a specialized version control system designed specifically for fleets of coding agents rather than human developers. It replaces traditional git workflows with a model built for high-volume, speculative, and concurrent changes. The system uses a local daemon that communicates via a typed gRPC API, allowing agents to manage isolated, copy-on-write workspaces that automatically reclaim space when an agent finishes its task.
Developers can integrate Reef into agentic workflows using its MCP server, which exposes twenty-one tools over stdio. These tools allow an AI client to manage workspaces, inspect logs, perform symbol-level diffs, and query change history without needing to parse complex command line output. The server is compatible with existing git and Jujutsu repositories and supports macOS and Linux through prebuilt binaries. By focusing on token efficiency and structured JSON responses, Reef ensures that agents can understand repository states with minimal computational overhead.
What you can do with it
- 1Manage isolated agent workspacesAn AI agent can create and run commands within a fresh, leased workspace that automatically cleans up after itself.
- 2Perform symbol-aware code analysisA developer can ask an agent to identify exactly which changes affected a specific function or variable definition.
- 3Revert accidental agent mutationsIf an agent makes a mistake, the system allows for a complete reversal of any previous operation using a global log.
- 4Minimize token usage for repository statusAn AI client can quickly determine the current state of a large repository using brief, structured data.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablereef-vcs/reef is public and reachablegithub.com/reef-vcs/reef ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/reef-vcs/reef ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubReef
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. Phase 3 (evidence, proposals, and landing) is under way: signed evidence, its artifact store, operator identities with session keys, and provenance records are on
main, not yet in a release. 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
- Snapshots, not commits. The working copy is always a snapshot. No staging area, no uncommitted state.
- Stable identity, mutable content. A change has a permanent ID that survives rebase and amendment.
- 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.
- Everything is undoable. A global operation log records every mutation, so any agent action reverts in one call (
reef undo <op>). - Workspaces are caches, not truth. Working directories are leased, copy-on-write, and reclaim themselves when the agent goes away. Deleting one loses nothing.
- Hub and ephemeral workspaces. One authoritative store per repository with lazy-fetching clients. Full clones are the exception.
- 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.
- 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. Phase 3's first tickets are on main and in no release yet. 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 firstreefcommand 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 creatematerializes a workspace on a change in a second or two on a 100k-file repository (under half a second on overlayfs),reef ws runruns a command inside a fresh workspace with the lease heartbeated for the life of the process and the workspace released on exit,reef ws moveputs another change in a workspace's directory without giving up its lease, andreef ws list|inspect|releasemanage 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
Backendtrait 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 gcreclaims 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 <dir>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 restorebrings 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.tomlin the repository declares stores such asnode_modulesortarget;reef store buildbuilds 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.
reefalone prints a one-screen guide,reef heresays which workspace you are in and what to run next, every error with a known fix carries it as ahintand anextcommand, 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
reefonPATH, afterreef init, with Reef not yet installed, and insidereef ws run: tool calls, failedreefcalls, 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 bybuflint and breaking-change checks in CI (ADR 0029). Thereefbinary 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 readandfile listlook at and revert what agents did, from a workspace or the checkout, with JSON for each and anextcommand 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 mcpserves 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 initwrites its entry for Claude Code, Codex and opencode (ADR 0035). -
Live operations.
SubscribeOperationsstreams the operation log as operations are recorded, filtered by repository, change, workspace, or agent, and resumes from a cursor;reef op watchprints 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 runandreef mcpreport it on their own,reef presence reportandclearreport finer activity,reef presence watchshows it, andreef ws renewrenews a lease held outsidews 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,uploadandlistdrive it (ADR 0042). -
Symbol-level diffs and history.
reef diff --symbolssays which definitions a change added, removed, changed or moved, and which call sites they affect (ADR 0043).reef historyand the MCPquery_changestool 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 --helpis 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 schemaprints 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-inreef-workspacesplugin (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 uiopens a read-only page in your browser, live from the operation and presence streams: every repository with its latest operation, each repository's smartlog, its workspaces and agents, with who is on which change, each lease's health, and disk use, and its activity feed, with a scrubber that replays any page at a past operation (ADR 0047). -
Garbage collection on a timer. The daemon runs
reef ws gcby itself every[gc] interval(a day by default), and GC leaves the user's own jj workspaces loadable (ADR 0040, ADR 0041). -
Python and TypeScript SDKs.
pip install reef-vcs(import reef) andnpm install reef-vcs: every API call as a typed method, generated from the schema, with page iterators, streams, the daemon's errors by kind withhintandnext, remote access with the daemon's key pinned, and a workspace block that holds a lease and reports presence asreef ws rundoes (ADR 0054, Python, TypeScript).
Reef MCP questions
What is Reef?
Reef is a version control system designed specifically for fleets of coding agents, replacing Git's working model with one suited for many concurrent, speculative authors.
How does Reef handle agent isolation?
Reef uses leased, copy-on-write workspaces that are automatically reclaimed when an agent's lease expires, ensuring no work is lost even if an agent dies.
Can I use Reef with Claude Code?
Yes, Reef provides a Claude Code plugin and can be initialized for Claude Code using the reef init command.