Oak doesn't run agents — you bring your own: Claude Code, Codex, Cursor, Aider, a script of your own. What Oak gives them is a version-control model that fits how they work, and a CLI built to be driven by a program as well as a person.
The model#
- One branch per session. Begin each agent run with
oak start "<summary>". A session you don't like gets closed, andmainnever notices. - The agent writes the description. Commits carry no message, so the agent's summary of what it did goes in
oak desc— and becomes the commit message onmain. - The agent publishes; a person merges. The agent ends with
oak finish, which leaves its branch pushed. You review and merge. - A worktree per agent. For many agents at once, give each agent its own worktree (
oak start "<summary>" --worktree), made from one clone. See Example: a fleet of agents.
Install the agent skill#
oak skill install # writes .claude/skills/oak-vcs/ — commit it
oak skill install --global # or ~/.claude/ for every project on this machine
The oak-vcs skill is a SKILL.md plus reference files in the open Agent Skills format. It teaches an agent to recognize an Oak repo (a .oak/ directory and no .git), to use oak instead of git, and the whole workflow on this site — including the traps, like commands that need a terminal unless given a name or flag. Committed to the repo, every collaborator's agent picks it up.
The files are baked into the CLI binary, so the skill always matches the CLI version that wrote it. After oak upgrade, the installed copy describes the old version: oak skill status says whether each copy is current or stale, and oak upgrade prints the install command to run.
oak skill status --json # each copy (this repo, user-wide) and whether it matches this CLI
oak skill show # print SKILL.md to stdout; `oak skill show commands.md` for a reference file
For agents that read AGENTS.md rather than skills (Codex, Cursor, and others), oak init offers to write an AGENTS.md explaining Oak, plus a one-line CLAUDE.md that points at it. An agent without skill support can also run oak skill show to read the guide that matches the installed CLI.
Rules to give an agent#
If you'd rather put it in your own prompt or AGENTS.md, this is the core:
This repo uses Oak (the `oak` CLI), not git. Never run git commands here.
- Begin every task with `oak start "<summary>"`: a branch from the latest main,
described and pushed.
- main lives on the server; never try to push to it.
- `oak commit` takes no message. Describe the branch once with `oak desc "..."`;
it becomes the commit message on main, so write it for a reviewer.
- Finish every task with `oak finish --desc-file <file> --json`.
- If `oak pull` reports a conflict, resolving it is your next action:
`oak conflict status`, edit the listed files, `oak pull --continue`.
- Do not run `oak merge`. A human merges.
- Prefer --json output. Commands that open a UI or prompt (bare `oak diff`,
`oak switch` with no name, `oak clone` with no repo, `oak split` without --plan)
need a terminal — use `oak diff --print`/`--stat`/`--json` and pass names.
- `oak reset` / `oak restore` ask for confirmation; pass -f only after
`oak status` shows what you'd discard.
- First push of a brand-new repo: `oak push --repo <org>/<name>`. Never guess the
org — ask if you don't know it.
- Lost? Run `oak agent state --json --compact`.
Starting a task#
oak start is how a task begins:
oak start "fix the auth redirect" # or --name BRANCH to choose the branch name
It creates a branch from main's head, named after the summary, carries over any uncommitted files, sets the summary as the branch description, and pushes the branch. In a brand-new repo it skips the push until the first push links it.
To pick up changes on main while you work, run oak pull. Push commits with oak push, or oak commit --push.
Machine-readable everything#
Every command an agent needs takes --json, and the results are designed to be acted on:
| Command | Use |
|---|---|
oak start "<summary>" --json | Begin a task. The receipt names the branch and whether the push went through (pushed, push_error). |
oak agent state --json --compact | One document: repo, branch, what's dirty, what's unpushed, and recommended_next_commands. The "where am I and what now?" call. |
oak status --json --compact | Bounded working-tree status. |
oak diff --json --hunks --max-bytes N | The diff, with a byte budget. |
oak commit --json, oak push --json, oak pull --json | Receipts with what happened and what to do next. |
oak finish --desc-file <file> --json | Describe, checkpoint, and publish in one step — see below. |
oak conflict status, oak conflict show --json | Conflict state, file by file. |
oak mark list --json | Every mark, such as server-prod, and how far behind main it is. |
oak ls, oak cat with --remote | Read a path on the server without cloning it: Reading a repository without a clone. |
oak branch triage --remote | Score every open branch, for an agent doing review (JSON). |
Many JSON payloads include recommended_next_commands: exact invocations for the natural next step. An agent should run one of those rather than improvise flags.
Exit codes are stable and meaningful — 3 repository locked (retry), 4 dirty working tree, 5 conflicts, 6 network/server/auth — so a wrapper can branch without parsing text. The table is in the CLI reference.
Finishing a task in one command#
oak finish --desc-file /tmp/desc.md --json
oak finish checks it can publish (is a remote linked? is anything blocking?) before changing anything else, then sets the branch description, checkpoints uncommitted changes, and pushes. If the preflight refuses, nothing has changed. If a later step is rejected, the JSON names the phase that completed and, where there is one, the command to run next.
Unconfirmed publications#
Sometimes the push request was sent but the reply never arrived (a timeout, a dropped connection), so neither the client nor you can tell whether it landed. oak finish and oak push report this as an unconfirmed publication (exit 6, publication_unconfirmed), and they give no command to retry. That is deliberate: a second push on a guess can duplicate or overwrite work. Reconcile read-only first.
oak agent state --refresh --json --compact # re-reads the server; shows interrupted publications
oak branch show BRANCH --remote --json # the head the server holds
Compare the heads. If the server holds your commit, the publication landed. If it holds the old head, it did not land (at that moment), and you can decide to push again. Seeing a head is evidence, not proof of who pushed it, so check the commit is yours. Exit 6 with publication_unconfirmed is the signal. The local record of the interrupted operation stays, and blocks further push and finish advice, until you explicitly forget it: checking the server (read-only) never removes it. oak agent publication forget OPERATION_ID --acknowledge-unknown --json removes that one record, without contacting the server, once you have decided to accept that its outcome stays unknown. The CLI refuses it unless both --acknowledge-unknown and --json are given.
Keeping a branch mergeable#
A pushed branch goes stale while other branches land on main. An agent that should keep its branch ready until someone merges it can wait on it instead of stopping:
oak branch wait --json
It holds until the branch is merged or closed, or until main moves and the branch no longer merges cleanly. On a conflict (exit 5, "event": "conflicts") its recommended_next_commands are the fix: oak pull, resolve the files it names, oak pull --continue, test, oak push, then oak branch wait again. A clean move of main needs nothing, since the server's squash merge doesn't need the branch up to date; pass --on-main-move to hear about those too and re-test. An agent whose commands have a time limit can pass --timeout SECONDS and call it again on "event": "timeout", or run it in the background.
Other ways to work#
- MCP server when your agent connects to a URL instead of running commands.
- Roots for release lines.
Credentials for unattended agents#
oak login needs a browser once. An agent on a server, in CI, or in a container should use an API key instead:
export OAK_API_KEY=oak_...
For an agent, prefer a key that can do no more than its job. A key for an agent works in one organization, reads and writes as a member of the groups you choose, and can push but never merge. An organization agent with only read and write scopes gives the agent its own name. See API keys and tokens.
Running many agents at once#
Give each agent its own branch and its own working tree, so they can't step on each other. Clone once, then start each task in a worktree beside the clone. A worktree is a second checkout on its own branch, made without downloading anything the clone already holds:
oak clone acme/web --shallow && cd web
oak start "fix login" --worktree # ../web-fix-login
oak start "add search" --worktree # ../web-add-search
claude -p "Work in ../web-fix-login, on the branch already started there ..." &
claude -p "Work in ../web-add-search, on the branch already started there ..." &
wait
oak branch triage --remote
oak worktree add DIR makes one on a new branch named after the folder, oak worktree list shows them all, and oak worktree remove DIR deletes one once its work is pushed. A branch is checked out in only one worktree at a time; oak switch refuses a branch another worktree has.
The example session walks through this end to end.
Feedback from agents#
Agents hit rough edges first. oak feedback files a bug or feature request from the terminal and returns a tracking reference (fb-N):
oak feedback -m "oak pull --json omits parent_head_after on fast-forward" --json
Without -m or --file it opens your editor on a terminal, and exits with an error (rather than hanging) when there's no terminal.
Privacy#
Oak makes no AI calls on your behalf and doesn't train on your code. Whatever agent you use is its own integration, with its own data policy.