# Oak

> Oak is the agentic substrate for software development: the version-control and storage layer autonomous coding agents build on. Mount remote repositories without a full clone, run a branch per task in parallel, snapshot up to 95% faster than git, and skip the per-commit message tax. Bring your own agent (Claude Code, Codex, Cursor): Oak is the version control system those agents push to, and it makes no AI calls of its own.

Oak keeps a familiar surface — repos, branches, PR-style merges, push/pull, webhooks, large-file support — on a Rust engine with content-addressed storage, content-defined chunking (BLAKE3 + FastCDC), and lazy filesystem mounts. It is designed for how agents actually work: high branch volume, constant snapshots, parallel sessions, and large files.

## Key facts

- Install: `curl -fsSL https://oak.space/install | sh` (macOS, Linux) or `irm https://oak.space/install.ps1 | iex` (Windows PowerShell), then `oak login` and `oak init`. Or hand your agent the prompt from the homepage "Copy prompt" button and let it install itself.
- Platforms: macOS (Apple Silicon and Intel), Linux (x86_64), and Windows (x86_64). Lazy mounts use FSKit on macOS, FUSE on Linux, and ProjFS on Windows. Linux ARM64 binaries are published on the GitHub releases page but the installer does not select them yet.
- Pricing: the Pro plan is $10/month and includes 100GB of storage and 3,000 CI minutes; Free includes 10GB and 2,000 CI minutes.
- Branch model: you always work on a feature branch locally; `main` exists only on the server; `oak merge` is a server-side squash; intermediate commits carry no message; the branch description is the source of truth and becomes the squash-commit message.
- CI: Oak runs CI natively. Workflows live at `.oak/workflows/<name>.yml` in a small documented YAML subset (`on:`, `env:`, named jobs, per-job `cache:`, shell-command steps) and fire on push, merge, revert, or manually. Per-repo CI secrets are encrypted at rest and redacted from logs. CI is the merge gate: a squash-merge onto main is refused while the branch head's CI is red or in flight; `oak merge --wait` rides it out and `oak merge --force` overrides it.
- Path permissions: declared in the repo as `.oak/PERMISSIONS` (CODEOWNERS-shaped, read from the `main` tip, last matching entry wins). Principals are `@user`, `@group/slug`, `*` (every repo reader), `@public` (the world), or none (org owners/admins only). For a repo reader the file narrows — restricted file names and sizes stay visible while their bytes are withheld. For an outsider `@public` widens instead, so a private repo can publish an open-source subtree; outsiders read it over the web UI or the read-only git snapshot, never `oak clone`/`pull`/`mount`.
- Performance: median (p50) latency is up to 95% lower than git on initial snapshots, dirty snapshots, large-binary diff/status, and agent setup workflows. git is faster on cold repo initialization and process spawn (one-time fixed costs).
- Data portability: `oak export <dest>` replays full branch history into a standard git repository, preserving author, email, and timestamp. A read-only git Smart-HTTP endpoint also serves the current `main` tree to stock `git clone`.
- Privacy: Oak does not train machine-learning models on your code and makes no AI calls on your behalf. Any coding agent you run alongside Oak is its own separate integration.

## Pages

- [Homepage](https://oak.space/): the pitch, the case against git for agents, benchmarks, and FAQ.
- [Docs](https://oak.space/docs): CLI reference, branch model, mounts, and HTTP API.
- [Pricing](https://oak.space/pricing): plans and limits.
- [Blog](https://oak.space/blog): how and why Oak is built.
- [Why I'm building Oak](https://oak.space/blog/git-is-forever): the founding note.
- [Dev log #1](https://oak.space/blog/dev-log-1): what shipped in the six weeks after launch.

## CLI quickstart

- `oak init [path]` — initialize a repository and create a personal feature branch parented on `main`.
- `oak clone [owner/repo] [dest]` — clone an Oak repo, or run without an argument to pick interactively. Use `--branch <name>` to clone a branch and `--shallow` to fetch only the latest default-branch commit.
- `oak mount <owner>/<repo> ./task` — project a repo into a working tree without a full clone; files stream in on first read.
- `oak switch -c <branch>` — start a feature branch for a task.
- `oak desc "<summary>"` — set the branch description (this becomes the commit message on merge).
- `oak commit` — local checkpoint on the feature branch (no per-commit message needed; does not publish).
- `oak commit --push` — checkpoint, then explicitly publish the current branch.
- `oak push --repo <owner>/<name>` — link and push a brand-new repo (owner must be an existing org slug).
- `oak pull` — fetch current-branch commits from the remote, then merge the parent branch into your branch.
- `oak fetch` — refresh local `main` from the remote without touching the working tree.
- `oak status --json --compact` and `oak agent state --json --compact` — stable, bounded machine-readable state for agents.
- `oak branch review <branch> --merge-preview --json` — checkout-free review evidence, changed-file summaries, triage detail, and merge prediction.
- `oak conflict status|show|take --json` — inspect or mechanically resolve in-progress merge, pull, or mount conflicts.
- `oak finish --desc-file <file> --json` — preflight, describe, checkpoint if needed, publish, and report the finalization phase.
- `oak merge` — server-side squash onto `main`. Add `--wait` to ride out the CI gate, `--force` to override it after reading the failure.
- `oak ci status|runs|logs <id>|rerun <id>` — the CI gate's visibility and recovery surface. `oak ci status` exits 0 on pass, 1 on fail, 3 while running.
- `oak skill install` — install the bundled `oak-vcs` agent skill into `.claude/skills/` (or `--global`), so an agent drives Oak correctly instead of reaching for git.
- `oak feedback -m "<text>" --json` — file a feature request or bug from the terminal; returns a tracking reference (`fb-N`).
- `oak export <dest>` — replay full history into a fresh git repo.

## CLI command surface

Documented command groups: start a repo (`init`, `clone`), snapshot changes (`status`, `info`, `agent state`, `conflict`, `diff`, `commit`, `restore`, `reset`), history (`log` incl. `-S`/`-G` pickaxe search, `hash`, `rev-parse --short HEAD` compatibility), branches (`branch list/show/diff/review/triage/rename`, `switch`, `desc`, `finish`, `close`, `split`, `merge`), server sync (`login`, `logout`, `whoami`, `push`, `pull`, `fetch`), CI (`ci status/runs/logs/rerun`), mounts and spaces (`mount` incl. `--branch` to mount an existing remote branch, `mount list/finish/end/forget`, `space new/repos/clean`), partial checkouts (`sparse list/set/add/disable`), sites (`site enable/disable/show/list`), local tooling (`export`, `archive`, `open`, `upgrade`, `maintenance compact`, `serve`, `skill install`, `completions`, `feedback`), and gated releases (`release new/list/show/edit/publish/upload/delete-asset/delete`, enabled with `OAK_FEATURES=releases`).

## HTTP API surface

The JSON API is rooted at `https://oak.space/api` and uses bearer API keys. Public docs cover auth (`/auth/*`, `/whoami`, GitHub OAuth/App connect callbacks), repositories (`/repos`, `/{owner}/{name}`, visibility, transfer, push/pull protocol, size), branches (list/create/show/merge/sync/close/reopen/rename), content and chunk storage (`commits/info`, `tree`, `raw`, `blobs/*`, `chunks/*`), CI (`ci/runs`, run detail, cancel, `ci/secrets`), path permissions (`path-permissions` and its propose endpoint), organizations, groups and audit, webhooks, ideas, organization sites, live import streams, and CLI release distribution endpoints. Full route details are on https://oak.space/docs.