AO keeps its durable state under ~/.ao. The daemon stores projects, sessions, pull-request facts, notifications, and typed project configuration in SQLite under ~/.ao/data; ~/.ao/running.json lets the desktop app and CLI find the running daemon.
The desktop app is the normal place to add projects and change settings. The CLI talks to the same daemon API when you need a scriptable path.
Add a project
In the desktop app, choose Add project and select a local repository. From the CLI:
ao project add --path /absolute/path/to/repo
To set the default agents while registering the project:
ao project add --path /absolute/path/to/repo \
--worker-agent codex \
--orchestrator-agent claude-code
AO also supports workspace projects, which contain a root repository and direct child repositories:
ao project add --path /absolute/path/to/workspace --as-workspace
Fresh installations include a Scratch project for work that does not need Git. Scratch sessions use AO-managed directories and do not support branches or pull-request claims.
Inspect and update configuration
ao project ls
ao project get <project-id>
ao project set-config <project-id> --worker-agent codex
set-config replaces the stored project configuration. Prefer project settings in the desktop app for interactive edits, or first inspect ao project get <project-id> --json before replacing configuration in a script. --config-json accepts a JSON object string, not a filename.
Current project configuration is typed. It covers the base branch, session prefix, environment variables, symlinks, setup commands, worker and orchestrator agents, agent options, project rules, reviewer agents, tracker intake, and container cleanup. Unknown fields are rejected instead of being silently ignored.
See Projects for the current field reference.
Daemon environment
The primary daemon listener is always loopback-only and unauthenticated. Its bind host is not configurable. Useful environment variables include:
| Variable | Default | Purpose |
|---|---|---|
AO_PORT | 3001 | REST, events, terminal mux, health, and control port |
AO_DATA_DIR | ~/.ao/data | Durable daemon data |
AO_RUN_FILE | ~/.ao/running.json | Daemon discovery file |
AO_REQUEST_TIMEOUT | 60s | REST request timeout |
AO_SHUTDOWN_TIMEOUT | 10s | Graceful shutdown deadline |
AO_ALLOWED_ORIGINS | packaged desktop origin | Additional trusted browser origins |
Do not set HOST=0.0.0.0 or proxy the primary daemon to a network. For phone access, use the separate authenticated listener created by Connect Mobile. See Remote access.
Chat and Terminal UI defaults
Every session commits to one interface at a time:
- Chat uses a structured, runtime-less provider controller with durable messages, activities, approvals, and usage.
- Terminal UI runs the agent's native terminal interface through AO's terminal runtime.
Choose the default for new sessions in project settings. You can also select it explicitly from the new-session flow or with ao spawn --mode chat|tui. Compatible Claude Code and Codex sessions can switch interfaces later without changing the AO session or worktree.