Each Git-backed session receives an isolated worktree and branch. By default, AO resolves the repository's Git default automatically instead of assuming main; multi-repository workspaces resolve their root and children independently. Worktrees share each repository's object database while keeping checked-out files separate.
Automatic resolution uses the selected remote's live symbolic HEAD, with its cached HEAD as an offline fallback. A fetched request-specific remote branch can still seed an explicitly requested session branch when the remote has no symbolic HEAD. AO does not use the branch currently checked out in the source repository.
AO records the resolved base ref for every repository in the session. Workspace and review diffs can therefore recompute their merge base after a rebase or after the repository default advances, without treating upstream-only changes as agent edits.
ao project add --path /path/to/repo --worker-agent codex
ao spawn --project my-repo --name fix-auth
Typed project settings
The daemon stores project configuration as validated JSON in SQLite. Relevant fields include:
| Field | Purpose |
|---|---|
defaultBranch | Base branch for new session worktrees; auto resolves each repository's Git default. |
env | Extra environment variables passed to agent runtimes. |
symlinks | Repository-relative paths linked into each workspace. |
postCreate | Commands run after workspace creation. |
agentRules, agentRulesFile | Standing worker instructions. |
Use ao project set-config <id> --help for flags or pass the complete typed object with --config-json.
Cleanup safety
ao session kill terminates the runtime, but preserves a worktree when cleanup cannot safely remove it. ao session cleanup reclaims eligible terminated workspaces and skips dirty ones; run with --dry-run first when you want to inspect the candidates.