# Working with agents

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.** Start each agent run on its own branch (`oak switch -c`, or a fresh [mount](/docs/mounts)). A session you don't like gets closed, and `main` never 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 on `main`.
- **The agent publishes; a person merges.** The agent ends by pushing its branch. You [review](/docs/reviewing) and [merge](/docs/merging).
- **Mount instead of clone.** For a big repo, or many agents at once, give each agent its own mount. See [Example: a fleet of agents](/docs/example-session).

## Install the agent skill

```bash
oak skill install            # writes .claude/skills/oak-vcs/ in this repo — commit it
oak skill install --global   # or ~/.claude/skills/oak-vcs/ 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 interactive commands that hang without a terminal. 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. Re-run `oak skill install` after `oak upgrade`.

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.

## Rules to give an agent

If you'd rather put it in your own prompt or `AGENTS.md`, this is the core:

```text
This repo uses Oak (the `oak` CLI), not git. Never run git commands here.
- Work on the current feature branch. 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 desc "...", oak commit, oak push
  (or `oak finish --desc-file <file> --json`).
- 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)
  hang without 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`.
```

## Machine-readable everything

Every command an agent needs takes `--json`, and the results are designed to be acted on:

| Command | Use |
|---|---|
| `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 ci status --json` | The merge gate's verdict (also via exit code). |
| `oak branch triage --remote --json` | Score every open branch, for an agent doing review. |

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](/docs/cli#exit-codes).

## Finishing a task in one command

```bash
oak finish --desc-file /tmp/desc.md --json
```

`oak finish` checks it can publish (is a remote linked? is anything blocking?) **before** changing anything, then sets the branch description, checkpoints uncommitted changes, and pushes. Inside a mount it also unmounts — but only once the push has succeeded. If any step fails, nothing is lost: the JSON names the step and the command to run next.

## 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:

```bash
export OAK_API_KEY=oak_...
```

For an agent, prefer a key that can do no more than its job — a **service account** with only `read` and `write` scopes (so it can push but never merge), or a key scoped to a single repo. See [API keys and tokens](/docs/api-keys).

## Running many agents at once

Give each agent its own branch *and* its own working tree, so they can't step on each other. With mounts that costs seconds, not a clone per agent:

```bash
oak space new acme && cd acme
oak mount acme/web ./fix-login/web
oak mount acme/web ./add-search/web
claude -p "Task fix-login, mounted at ./fix-login/web ..." &
claude -p "Task add-search, mounted at ./add-search/web ..." &
wait
oak branch triage --remote
```

The [example session](/docs/example-session) walks through this end to end, and [Agent spaces](/docs/spaces) covers the scaffolding.

## 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`):

```bash
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.