# Introduction

Oak is the **agentic substrate** for software development: the version-control and storage layer that coding agents — and the people directing them — build on. It's where your agent (Claude Code, Codex, Cursor, or anything else) reads, writes, branches, and publishes code and assets.

Oak doesn't run agents. Bring your own; Oak is the version control system they push to. It makes no AI calls on your behalf and never trains on your code.

## The five ideas

Everything in these docs follows from five decisions. If you only read one section, read this one.

1. **A branch is a task.** Not a long-lived line of development — one unit of work, usually one agent session. `oak init` and `oak clone` put you on a fresh personal branch, and branches are cheap enough to make one per 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 have to clone.** `oak mount` puts a working tree on top of a remote repo and fetches files as they're read, so a 20 GB monorepo is editable in seconds — and ten parallel tasks means ten mounts, not ten clones.

Around that core, oak.space adds what a team needs to land changes safely: [native CI](/docs/ci) that gates merges, [path permissions](/docs/path-permissions) declared in the repo, organizations, webhooks, and a JSON API.

## Where to start

| If you want to… | Read |
|---|---|
| Install the CLI and sign in | [Install and sign in](/docs/install) |
| Get a repo onto Oak and merge your first change | [Quickstart](/docs/quickstart) |
| Translate what you know from Git | [Coming from Git](/docs/coming-from-git) |
| Point a coding agent at Oak | [Working with agents](/docs/agents) |
| Run several agents on one big repo | [Example: a fleet of agents](/docs/example-session) |
| Set up CI | [Continuous integration](/docs/ci) |
| Look up a command or flag | [CLI reference](/docs/cli) |
| Script against oak.space | [HTTP API reference](/docs/api) |

## Platforms

The `oak` CLI ships for **macOS** (Apple Silicon and Intel), **Linux x86_64**, and **Windows x86_64**. Lazy mounts use each OS's own virtual-filesystem layer — FSKit on macOS 26+, FUSE on Linux, the Projected File System on Windows. Linux ARM64 binaries are published on the [GitHub releases page](https://github.com/oakdotspace/oak/releases) but the installer doesn't select them yet.

## For agents

Every page has a **Copy page** button and a **.md** link that return its Markdown source. [`/docs/llms-full.txt`](/docs/llms-full.txt) is every page in one file. And `oak skill install` drops an `oak-vcs` skill into your repo so agents pick up the workflow without being told — see [Working with agents](/docs/agents#install-the-agent-skill).

## Your data stays yours

`oak export` replays any Oak repo's full history into an ordinary Git repository — authors, emails, and timestamps intact. It's the documented escape hatch, and it always works. See [Git import, export, and interop](/docs/git).