Projects

A project is a repository, a multi-repository workspace, or an AO-managed Scratch directory. AO stores project identity and typed configuration in its database; there is no current agent-orchestrator.yaml lookup or global YAML registry.

Project kinds

Add and manage projects from the desktop sidebar. The equivalent CLI commands are:

ao project add --path /absolute/path/to/repo
ao project add --path /absolute/path/to/workspace --as-workspace
ao project ls
ao project get <project-id>
ao project rm <project-id>

Current configuration fields

Project settings expose the fields that AO consumes at spawn time:

symlinks and agentRulesFile must remain inside the repository. AO rejects absolute paths and traversal. Scratch rejects Git-only fields such as defaultBranch and symlinks.

defaultBranch: "auto" resolves each repository independently. AO selects the remote named by Git's checkout.defaultRemote, otherwise origin, otherwise the repository's only remote. It asks that remote for its symbolic HEAD, fetches the exact advertised branch, and can fall back to the same remote's cached HEAD while offline.

AO never treats the currently checked-out branch, main, or master as an inferred default. If a repository has no authoritative remote default (or has ambiguous remotes), spawn returns DEFAULT_BRANCH_UNRESOLVED. For a single repository or workspace root, set defaultBranch explicitly. For a workspace child, configure its primary remote with checkout.defaultRemote when needed and set its cached remote HEAD with git remote set-head. Repositories initialized by AO are the exception because AO records its branch choice when it creates them; older AO-created repositories are recognized and backfilled on first resolution.

Worker and orchestrator roles

Workers implement tasks and own code changes. Orchestrators supervise a project and coordinate workers. Configure their harnesses independently:

{
  "worker": {
    "agent": "codex",
    "agentConfig": { "model": "gpt-5.4", "permissions": "bypass-permissions" }
  },
  "orchestrator": {
    "agent": "claude-code",
    "agentConfig": { "model": "claude-opus-4" }
  }
}

The exact model names come from the installed provider. AO reuses the provider CLI and its existing authentication; it does not store provider tokens in project configuration.

Session interface

The role selects what a session does; the interface selects how you interact with its agent.

• Chat is available when the installed harness advertises native Chat support. Current drivers cover Codex, Claude Code, OpenCode, and Droid.
• Terminal UI remains available across the wider agent adapter catalog.
• Compatible Claude Code and Codex sessions can hand off between Chat and Terminal UI while keeping their AO session and worktree.

Choose the default interface in desktop project settings. Override it for a single CLI spawn with --mode chat or --mode tui.

Setup and rules

Use env, symlinks, and postCreate for repeatable workspace setup. A failing postCreate command prevents the agent from starting, so keep setup deterministic.

Use agentRules or agentRulesFile for worker instructions and orchestratorRules for supervision-specific guidance. AO combines inline and file-based worker rules when both are present.

Reviewer agents

Reviewer harnesses are configured separately from workers. AO currently supports Claude Code, Codex, and OpenCode reviewers. If none is configured, AO reuses the worker harness when it is review-capable, otherwise it falls back to Claude Code.

Review runs are available in the desktop inspector and through:

ao review trigger <worker-session-id>
ao review ls <worker-session-id>

Update from the CLI

For a complete replacement, pass the project config as a JSON object string:

ao project set-config <project-id> \
  --config-json '{"worker":{"agent":"codex"}}'

Run ao project set-config --help for focused flags and --clear. Because replacement is atomic, inspect the existing project first when scripting updates.

Most users should keep tmux.

Choose The Workspace

workspace controls how AO isolates each session's code.

workspace: worktree

Use worktree unless your repository has tooling that behaves badly with git worktrees.

Prepare Each Session

Use symlinks for files agents need but should not be copied or committed:

symlinks:
  - .env
  - .claude

Paths are relative to the project root. Missing paths are skipped with a warning.

Use postCreate for setup commands that must run inside each new workspace:

postCreate:
  - pnpm install
  - cp .env.example .env

If a postCreate command fails, AO does not start the agent for that session. Keep these commands deterministic.

Give Agents Project Rules

Use agentRules for short project-specific instructions:

agentRules: |
  Use conventional commits.
  Do not touch database migrations unless the issue asks for it.
  Run pnpm lint and pnpm test before pushing.

Use agentRulesFile when the rules are long or already versioned:

agentRulesFile: AGENTS.md

If both are set, AO includes both.

Use orchestratorRules for instructions that only apply to the orchestrator session:

orchestratorRules: |
  Split large issues into small worker tasks.
  Review worker output before asking for a merge.

Split Orchestrator And Worker Roles

You can run one agent/model for orchestration and another for implementation:

orchestrator:
  agent: claude-code
  agentConfig:
    model: claude-opus-4

worker:
  agent: codex
  agentConfig:
    model: gpt-5.4
    permissions: permissionless

Use this when planning/review needs a stronger model but routine implementation can use a faster or cheaper worker.

Choose A Reviewer

Reviewer agents are configured independently from worker and orchestrator agents:

reviewers:
  - harness: kilocode

Built-in reviewer harnesses are aider, agy, amp, auggie, autohand, claude-code, cline, codex, copilot, crush, cursor, devin, droid, grok, kilocode, kimchi, kiro, kimi, opencode, and pi. Kilo Code requires the @kilocode/cli package and a configured model provider (/connect, kilo auth login, or a supported provider environment variable). AO launches Kilo Code in the worker checkout with a read-only review policy and its own GitHub/AO reporting instructions. It does not invoke Kilo's local /review command or parse kilo run --format json; the reviewer posts through gh api and records its verdict through ao review submit, like the other AO reviewer harnesses.

Agy, Devin, Droid, Kimchi, and Kimi reviewer support is experimental and host-trusted. Grok, Crush, Auggie, Cline, and Autohand are experimental user-approved reviewers: AO strengthens their reviewer system prompt and leaves native permission prompts enabled instead of passing broad unattended flags. Their readonly, plan, or approval modes constrain ordinary model behavior but are not OS isolation; terminal users, project plugins, tools, and network access may retain host authority.

Tracker And SCM

AO usually infers tracker and SCM from the registered repository. Override them only when needed.

tracker:
  plugin: github

scm:
  plugin: github

Built-in trackers:

Built-in SCM plugins:

Extra keys under tracker and scm are passed to the plugin:

tracker:
  plugin: linear
  teamId: ENG

scm:
  plugin: github
  webhook:
    enabled: true
    path: /api/webhooks/github
    secretEnvVar: GITHUB_WEBHOOK_SECRET

For external plugins, use package or path:

tracker:
  package: "@acme/ao-plugin-tracker-jira"
  projectKey: APP

Tune Automation Per Project

Project-level reactions override global reaction settings:

reactions:
  ci-failed:
    retries: 3
  approved-and-green:
    auto: false

See Reactions for the event list and action behavior.

Session Recovery

Use these only when you need explicit recovery behavior.

orchestratorSessionStrategy: reuse
opencodeIssueSessionStrategy: reuse

orchestratorSessionStrategy accepts:

opencodeIssueSessionStrategy accepts reuse, delete, or ignore.

Local Reference

These fields are valid in a local project config:

Identity fields such as projectId, path, storageKey, originUrl, and sessionPrefix belong to the global registry, not the local config.

Common Problems

The project does not appear in the dashboard
Run ao start from the repository root so AO can register the project. If the repo moved, remove and re-add or relink the project instead of editing storageKey manually.

The agent starts without environment variables
Add .env or the relevant tool config directory to symlinks. AO does not copy secrets into worktrees by default.

Setup fails before the agent starts
Check postCreate. A failing command stops the session before the agent launches.

Two projects get confusing session names
Set sessionPrefix in the global project registry or through project registration/settings. Session prefixes must use letters, numbers, underscores, or hyphens.

GitHub or GitLab calls fail
Make sure the corresponding CLI or token is authenticated for the plugin you use. AO does not store provider tokens in project config.

Next Steps