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.
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, so the one-time mount setup applies.
Create a space#
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#
- Pick a slug — short and kebab-case, like
fix-auth-redirect. It becomes the task directory and the start of each branch name. - See what's available:
oak space reposlists the org's repos (add--jsonfor agents). - Mount each repo the task needs under the task directory:
oak mount acme/web ./fix-auth-redirect/web - Work inside each mount.
oak status,diff,commit, andpushall act on that mount's branch. - Finish each repo you touched:
This sets the description, checkpoints, pushes, and unmounts — unmounting only after the push succeeds.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 - Sweep up:
oak space cleantears down every mount in the space that has nothing uncommitted or unpushed. Add a path to clean one task;--forcealso 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#
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 walks through fanning out, reviewing, and merging end to end.