# Agent spaces

An **agent space** is a directory where coding agents work across one organization's repos. Each task gets its own subdirectory, and inside it you mount whichever repos the task needs — each on its own branch. It's like a set of Git worktrees, except there's no clone behind any of them, so starting a task takes seconds.

```text
acme/                          ← the space (one per org)
├── AGENTS.md
├── fix-auth-redirect/         ← one task
│   └── web/                   ← a mount of acme/web, on branch fix-auth-redirect--a1b2c3d4
└── unify-errors/              ← a cross-repo task
    ├── web/                   ← mount of acme/web,   branch unify-errors--…
    └── api/                   ← mount of acme/api,   branch unify-errors--…
```

Spaces are built on [lazy mounts](/docs/mounts), so the [one-time mount setup](/docs/mounts#setting-up-mounts) applies.

## Create a space

```bash
oak space new acme              # creates ./acme
oak space new acme ~/work/acme  # …or somewhere else
```

This writes:

| File | Purpose |
|---|---|
| `AGENTS.md` | The workflow, written for an agent: picking a task slug, mounting, finishing, and the mount traps to avoid. Edit it to add your team's conventions. |
| `CLAUDE.md` | A one-line `@AGENTS.md` import, for Claude Code. |
| `.claude/settings.json` | Pre-approves the `oak` commands agents need, and lists mounts when a Claude Code session stops. |
| `.oak-space` | Marks the directory as a space for the org. |

Nothing is cloned or mounted yet.

## The per-task loop

1. **Pick a slug** — short and kebab-case, like `fix-auth-redirect`. It becomes the task directory and the start of each branch name.
2. **See what's available:** `oak space repos` lists the org's repos (add `--json` for agents).
3. **Mount each repo the task needs** under the task directory:
   ```bash
   oak mount acme/web ./fix-auth-redirect/web
   ```
4. **Work inside each mount.** `oak status`, `diff`, `commit`, and `push` all act on that mount's branch.
5. **Finish each repo you touched:**
   ```bash
   oak mount finish ./fix-auth-redirect/web --desc-file desc.md --json   # from the space root
   # or, from inside the mount: oak finish --desc-file desc.md --json
   ```
   This sets the description, checkpoints, pushes, and unmounts — unmounting only after the push succeeds.
6. **Sweep up:** `oak space clean` tears down every mount in the space that has nothing uncommitted or unpushed. Add a path to clean one task; `--force` also removes dirty mounts, discarding their changes.

Each repo's mount is independent: describe, commit, and push them separately, even within one cross-repo task.

## Take stock

```bash
oak space inventory --verify-local --include-ci --json
```

`oak space inventory` walks a directory tree and reports every Oak checkout and mount it finds. `--verify-local` adds each one's dirty-file and unpushed-commit counts; `--include-ci` adds the CI state of each one's head. It's an observation, not a guarantee — it never certifies that a directory is safe to delete.

## Running agents in a space

Launch agents from the space root so they read `AGENTS.md`, and tell each which task directory is its own. [Example: a fleet of agents](/docs/example-session) walks through fanning out, reviewing, and merging end to end.