Version control for agents

Oak

This repository is Oak, version control built for you and your agents. The root is a Cargo workspace: a reusable VCS library and the oak command-line client. The server, web app and public site live in server/, a workspace of its own.

Oak doesn't run agents. Bring your own (Claude Code, Codex, Cursor, …) and it works through the oak CLI. A branch is one unit of work, usually one agent session. The branch description takes the place of per-commit messages, and shallow and sparse clones let you start on a big repo without pulling all of it.

CratePathcrates.ioWhat it is
oakvcs-corecore/oakvcs-coreThe VCS foundation: BLAKE3 content hashing, content-defined chunking, diff/merge, the Blob/Manifest/Commit/Tree data model, and an optional client-side local repository (SQLite + git backends).
oakvcs-clicli/oakvcs-cliThe oak binary that builds on oakvcs-core.

Using the library in your own project

oakvcs-core is usable on its own — e.g. to build an Oak integration into another tool or engine. Pull in just the content-addressed data model and hashing (no SQLite/git) with default features off:

[dependencies]
oakvcs-core = { version = "0.114.0", default-features = false }

The crate is published as oakvcs-core but imported as oak_core.

Add the default local-repo feature when you also want the on-disk Repository (SQLite) backend.

Installing the CLI

Oak is in public beta (v0.114.0). The quickest way in is the prebuilt oak binary:

curl -fsSL oak.space/install | sh

The sh installer supports macOS (Apple Silicon and Intel) and Linux (x86_64) — it picks the native binary for the machine it runs on. After install, oak upgrade updates the binary in place.

There is one release line during the beta. We release once a day, at 2 PM Pacific, on days when something landed.

Linux ARM64 binaries are published too, but the installer doesn't select them yet; download the Linux ARM64 build below for now.

Downloads

Each link serves the latest oak for that platform:

PlatformDownload
macOS, Apple Siliconoak-darwin-arm64
macOS, Inteloak-darwin-x86_64
Linux x86_64oak-linux-x86_64
Linux ARM64oak-linux-arm64
Windows x86_64oak-windows-x86_64.exe

Add /sha256 or /minisig to a link for its checksum or minisign signature, and swap latest for a version (v0.114.0) to pin one. Make the file executable, rename it oak (oak.exe on Windows) and put it on your PATH. What changed in each release is in docs/ as release-X.Y.Z.md.

Windows (x86_64)

The curl … | sh installer is Unix-only; Windows has a PowerShell counterpart:

irm https://oak.space/install.ps1 | iex

It installs oak.exe to %USERPROFILE%\.local\bin and adds that directory to your user PATH. You can also take oak-windows-x86_64.exe from Downloads, or build from crates.io with cargo install oakvcs-cli. oak upgrade then updates it in place.

Prefer to build from crates.io? Install with Cargo instead (works on macOS, Linux, and Windows — the TLS stack uses rustls + ring, so no C/NASM build toolchain is required):

cargo install oakvcs-cli   # builds and installs the `oak` binary

To set up shell completion for bash, zsh or fish:

oak completions --install

It writes the script where your shell loads completions from and prints any line your startup file still needs. oak completions <shell> prints the script instead (elvish and powershell too).

Teaching your agent to drive Oak

Oak bundles an agent skill in the open Agent Skills format — a SKILL.md plus reference files that tell a coding agent how Oak differs from git (flat branches off main, messageless commits, branch descriptions, marks) so it stops reaching for git status:

oak skill install            # into this repo's .claude/skills/ — commit it
oak skill install --global   # into ~/.claude/skills/ for every project

The files are baked into the binary, so the installed skill always documents the CLI version that wrote it; re-run after oak upgrade to refresh it. The source of truth is cli/src/commands/skill/oak-vcs/.

A task starts and ends with two commands:

oak start "fix the login redirect"   # branch from main, described, pushed
oak finish --desc-file desc.md       # describe, checkpoint, publish

Using Oak from an MCP client

Agents with a shell do best with the CLI and its skill (oak skill install). For clients that connect to a URL, like Claude's connectors, Oak runs an MCP server at https://oak.space/mcp. See MCP server.

Marks

Oak runs none of your code on the server: test locally, and merge once you're up to date with main. A mark records what has passed what: a named pointer to a commit on main that people and bots move forward (server-good, server-prod, cli-released). A mark can require others to be at or past a commit before it moves there, and a deploy is a mark a machine follows.

oak mark list                                   # each mark and how far behind main it is
oak mark move server-good main --note "tests pass"
oak mark follow server-prod --run scripts/deploy.sh   # on the deploy machine
oak report main --name tests --body "412 passed"      # say how it went

A report is free text about a commit under a name; its first line shows on History. See the marks docs and reports.

Working with large monorepos

Two ways to avoid pulling a whole monorepo, and they combine:

  • Shallow clones — oak clone <org>/<repo> --shallow takes only the newest commit, with the full working tree and none of the history.

  • Sparse (partial) clones — Perforce-style, when you want a plain on-disk checkout scoped to a subtree:

    oak clone acme/monorepo --path services/api --path libs/shared
    oak sparse add libs/proto   # widen the cone
    oak sparse disable          # back to a full checkout
    

    Add --json to a named Oak clone for one machine-readable acquisition receipt. It records the requested history and cone, the resulting exact head/manifest, observed object and unique chunk counts, materialization counts, and explicitly unavailable transport/disk measurements. Legacy fallback phases remain visible rather than being folded into a false single-pass claim.

    Only files under the cone are downloaded and written; the rest of the tree is listed but its content is withheld, and commits carry the out-of-cone paths forward untouched (narrowing never deletes them). The same withhold-content mechanism powers server-side path permissions — directory-level access set on the server as path rules owned by groups (see oak access, oak owners and oak group). OAK_ALLOW_PARTIAL_CLONE=1 is a separate recovery flag that skips, rather than errors on, blobs a broken server failed to ship.

Every clone first negotiates a bounded metadata integrity profile; merely being logged in does not trigger object-store probes. If the proof runs out of its history/tree/path or wall-time budget, the result is inconclusive (exit 8), not a content failure: Oak never narrows or waives on its own, and recommends the exact --shallow retry first. When the server issued a snapshot pin for that inconclusive proof, it also offers the explicit --allow-unverified-integrity retry, which proceeds without proving completeness while the pull still verifies transferred hashes. --allow-legacy-scope is the separate, explicit compatibility waiver for an accessible older server that cannot prove branch/depth/sparse scope. Use oak doctor --repo ORG/REPO --verify metadata --json for a cheap bounded diagnostic and the platform-admin oak doctor blob HASH --repo ORG/REPO --json for bounded target byte evidence (--depth N --branch NAME selects a wider explicit history scope).

Building from source

cargo build --workspace        # builds oak-core + the oak binary
cargo test  -p oakvcs-cli      # CLI tests (incl. wiremock HTTP tests)
make build                     # release build + the CLI release tooling
make release-proof             # non-mutating launch/release readiness proof

The CLI depends on oak-core via an in-workspace path, so a plain cargo build works against the local core/ checkout with no extra setup. See docs/release-readiness.md for the release proof and crates.io publish-order checks.

Feedback

oak feedback files a feature request or bug report against Oak from the terminal and prints back a tracking reference (fb-N). It takes -m, a file, or stdin, opens $EDITOR with a template when given nothing on a TTY, and exits rather than blocking when there's no terminal — so an agent can file one mid-task without stalling:

oak feedback -m "oak diff --print panics on a closed pipe" --json

License

Apache-2.0. See LICENSE. The server in server/ is AGPL-3.0-only; see server/LICENSE.

AI

This repo was written almost entirely using AI with human oversight. If you see anything that needs fixed or would like to contribute, please email zach@oak.space or reach out on Discord.