Introduction

What Oak does today, the five ideas behind it, and where to go next.

Markdown

All pages

Oak is version control, and the hosting around it, for people who work alongside coding agents. Your agent (Claude Code, Codex, Cursor, or anything else that can run a shell command) reads, writes, branches and publishes through the oak CLI, and you review and merge what comes back.

Oak doesn't run agents. You bring your own. Oak makes no AI calls on your behalf and doesn't train on your code.

The five ideas#

Most of what's in these docs follows from five decisions.

  1. A branch is a task. It's one unit of work, usually one agent session, rather than a long-lived line of development. oak init and oak clone put you on a fresh personal branch, and you make a new one for each task.
  2. Commits are checkpoints; the branch description is the message. oak commit takes no -m. What the change is gets written once, on the branch, with oak desc.
  3. main lives on the server, and only merges reach it. You never commit to main locally and direct pushes to it are refused. Publishing a branch and merging it are separate steps, and merging is a human's call.
  4. Merging squashes. A merged branch becomes exactly one commit on main, whose message is the branch description. main reads as one line per task.
  5. You don't need the whole repo. A shallow clone leaves out the history, a sparse clone checks out only the directories you name, and oak ls, oak cat and oak grep --remote read a repo on the server without cloning it.

Around that, oak.space has what a group needs to land changes: marks for what passed and what's deployed, access rules per directory, organizations, webhooks, and a JSON API.

Where to start#

If you want to…Read
Install the CLI and sign inInstall and sign in
Get a repo onto Oak and merge your first changeQuickstart
Translate what you know from GitComing from Git
Point a coding agent at OakWorking with agents
Run several agents on one big repoExample: a fleet of agents
Record what passed, or deploy from a commitMarks
Look up a command or flagCLI reference
Script against oak.spaceHTTP API reference

Platforms#

The oak CLI ships for macOS (Apple Silicon and Intel), Linux x86_64, and Windows x86_64. A Linux ARM64 binary is published too, but the installer doesn't select it yet; see Install.

For agents#

Every page has a Copy page button and a .md link that return its Markdown source, and /docs/llms-full.txt is every page in one file. oak skill install puts an oak-vcs skill into your repo so agents pick up the workflow without being told. See Working with agents.

Getting your data out#

oak export replays an Oak repo's full history into an ordinary Git repository, keeping each commit's author, email, and timestamp. See Git import, export, and interop.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].