Parallel work
Run isolated worker sessions across issues without mixing branches, terminals, or conversations.
Start each task as its own worker session. Git projects receive separate worktrees and branches; Scratch receives separate Orchestrator-managed directories. Chat conversations and Terminal UI runtimes are session-scoped.
Start sessions from desktop
Choose a project, open a new task, pick the worker agent at the top of the model menu, and send its brief. Repeat for each independent task. The sidebar and sessions board update from the daemon's event stream without a reload.
Start sessions from the CLI
ao spawn --project web --name issue-42 --issue 42 --mode chat
ao spawn --project web --name issue-43 --issue 43 --mode tui
ao spawn --project api --name auth-fix --prompt "Fix token refresh" --harness codexao spawn accepts flags rather than positional issue identifiers. There is no current ao batch-spawn; invoke ao spawn once per task or let an orchestrator create workers.
What is isolated
| Resource | Isolation |
|---|---|
| Files | A worktree or Scratch directory per session |
| Branch | A generated ao/<session-id>/root branch unless overridden |
| Agent controller | One committed Chat or Terminal UI controller per session |
| Chat history | Durable, session-scoped conversation projection |
| Terminal | Session runtime or session-scoped worktree shell |
| Browser preview | Dedicated target; temporary profile by default, or deliberately shared named profile |
Orchestrator-managed worktrees live under ~/.ao/data/worktrees, not ~/.worktrees. Changes outside a worktree, such as pushes, pull requests, CI runs, and review comments, are shared on the repository host.
Standalone workers use a plain directory without a project. Start one with --standalone --agent <agent>; do not combine it with project or Git options.
For issue association, choose --tracker-provider github|gitlab when needed. Automatic issue intake must be enabled in both daemon and project settings.
Inspect and clean up
ao session ls
ao session ls --project web --json
ao session get <session-id>
ao session kill <session-id>
ao session cleanup --dry-run
ao session cleanupCleanup reclaims eligible workspaces for terminated sessions. Dirty registered worktrees are preserved and skipped.
To check daemon health, use ao status. It does not list sessions.
Follow the work
Open a session to see its Chat timeline or live terminal, pull-request summary, review runs, changed files, and browser preview. Lifecycle updates keep CI, reviews, mergeability, activity, and notifications attached to the owning session.