Start each task as its own worker session. Git projects receive separate worktrees and branches; Scratch receives separate AO-managed directories. Chat conversations and Terminal UI runtimes are session-scoped.
Start sessions from desktop
Choose a project, create a new task, give it a short display name, then select the worker harness and Chat or Terminal UI. 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 codex
ao 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 selected-session browser target and ephemeral profile |
AO-managed worktrees live under ~/.ao/data/worktrees, not ~/.worktrees. External side effects such as pushes, pull requests, CI runs, and review comments are naturally shared with the repository host.
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 cleanup
Cleanup reclaims eligible workspaces for terminated sessions. Dirty registered worktrees are preserved and skipped.
ao status reports daemon health; it is not the session list and does not have --watch.
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.