Oak
This repository is the open-source heart of Oak:
version control at the speed of agents. It's developed as a Cargo
workspace: a reusable VCS library plus the oak command-line client that
agents drive.
Bring your own agent (Claude Code, Codex, Cursor, …); Oak is the foundation it reads, writes, branches, and collaborates through. The substrate is shaped around how agents actually work — branch-per-session as the unit of work, branch descriptions in place of per-commit messages, and content-addressed lazy mounts that get an agent editing any repo in seconds. Because it's content-addressed and hydrates on demand, it's also far faster than git for agent workloads — but the speed is a consequence of the design, not the pitch.
| Crate | Path | crates.io | What it is |
|---|---|---|---|
oakvcs-core | core/ | oakvcs-core | The 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-cli | cli/ | oakvcs-cli | The 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.103.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 + read-only git) backends.
Installing the CLI
Oak is in public beta (v0.103.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.
Linux ARM64 binaries are published too, but the installer doesn't select them
yet; grab oak-linux-arm64 from the latest GitHub
release for now.
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 grab the prebuilt oak-windows-x86_64.exe from
the latest GitHub
release (rename it to
oak.exe and put it on your PATH), or build from crates.io with
cargo install oakvcs-cli. oak upgrade then updates it in place.
oak mount on Windows uses the Projected File System (ProjFS), an optional
Windows feature. Enable it once per machine from an elevated PowerShell:
Enable-WindowsOptionalFeature -Online -FeatureName Client-ProjFS -NoRestart
(or Settings → Apps → Optional features → "Windows Projected File System"). Everything else — clone, push, pull, commit — works without it.
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
Shell completion is generated on demand — bash, zsh, fish, elvish, and
powershell are supported. For the current session:
source <(oak completions bash)
Or write the script wherever your shell loads completions from, e.g.
oak completions bash > ~/.local/share/bash-completion/completions/oak.
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, messageless commits, branch descriptions, mounts, the CI gate) 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/.
CI and the merge gate
An Oak server runs CI natively from workflow files at .oak/workflows/*.yml,
and merges onto main are gated on it: the server refuses a squash-merge
(HTTP 412) while the branch head's CI is red or still in flight. The CLI is the
visibility and recovery surface for that gate:
oak ci status # CI for the current branch head — exit 0 pass, 1 fail, 3 running
oak ci runs [--limit N] # recent runs: id, workflow, branch, commit, status, duration
oak ci logs <run-id> # step-by-step logs
oak ci rerun <run-id> # re-dispatch at the same commit, for infra flakes
oak ci cancel RUN_ID --commit HASH --json # exact ordinary push/merge run only
oak merge --wait # ride the gate out instead of polling
oak merge --force # override it, after reading the failure
Cancellation requires an explicit run ID and full lowercase commit hash. It rejects manual, protected, release, terminal, moved, and unknown runs before mutation. A successful receipt confirms the control-plane cancellation record; stopping already-running execution remains best effort and is not confirmed.
Working with large monorepos
Two ways to avoid pulling a whole monorepo:
-
Lazy mounts —
oak mount <org>/<repo>puts a working tree on top of the remote and hydrates files on demand (FSKit on macOS, FUSE on Linux, ProjFS on Windows). Best default for very large repos. -
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 checkoutOnly 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 read access, declared in the repo as a CODEOWNERS-shaped
.oak/PERMISSIONSfile rather than configured in the platform.OAK_ALLOW_PARTIAL_CLONE=1is 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 only the proof's
history/tree/path budget is exhausted, Oak prints an exact retry using
--allow-unverified-integrity 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 blob info 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.
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 [email protected] or reach out on Discord.