AO's daemon owns a durable project registry in SQLite. The desktop sidebar shows every registered project and its sessions; there is no single agent-orchestrator.yaml containing a projects: map.
Add projects
Use Add project in the desktop app, or register an existing local repository:
ao project add --path /absolute/path/to/web --id web
ao project add --path /absolute/path/to/api --id api
ao project ls
ao project add requires a local path. It does not clone remote URLs. ao start only resolves and opens the desktop app; it does not register the current directory.
Workspace and Scratch projects
Register a parent directory containing direct child repositories as one workspace project:
ao project add --path /absolute/path/to/product --as-workspace
Fresh installations also have Scratch for tasks that do not require Git. Scratch sessions cannot use --branch or --claim-pr.
Give each project its own roles
Open each project's settings and choose its worker, orchestrator, model, rules, setup, reviewers, and default session interface. Project configuration is typed and independent; changing one project does not set global YAML defaults for the others.
Spawn in the right project
ao spawn --project api --name api-issue --issue 42 --mode chat
ao spawn --project web --name web-fix --prompt "Fix the header" --mode tui
When --project is omitted, AO can resolve AO_PROJECT_ID, the current registered repository, or Scratch when it is the only project. Supplying the project explicitly is clearest in scripts.
Inspect across projects
The desktop sidebar and sessions board are the live multi-project view. From the CLI:
ao project ls
ao session ls
ao session ls --project api
ao session ls --project api --json
ao status reports daemon health rather than project sessions. It supports --json, not --watch or a project filter.
Stop and clean up
Kill one session with ao session kill <session-id>. Use ao session cleanup --dry-run before reclaiming eligible terminated-session workspaces. Dirty worktrees are preserved.
ao stop stops the daemon and takes no project argument. Closing a desktop-owned app normally reaps its linked daemon; a headless daemon remains until explicitly stopped.
Use mobile across projects
Connect Mobile exposes the same registered projects and session modes through the authenticated mobile listener. Mobile prefers Chat for new workers and orchestrators when a compatible harness is installed, while Terminal UI remains selectable.