Projects

A project is one repository that AO can run agents against. The global registry remembers the project identity; the local agent-orchestrator.yaml controls how sessions behave inside that repo.

Most teams only need these fields:

agent: claude-code
runtime: tmux
workspace: worktree

symlinks:
  - .env

postCreate:
  - pnpm install

agentRules: |
  Use pnpm.
  Run pnpm test before pushing.
  Keep PRs focused.

Choose The Agent

agent selects the coding agent AO launches for worker sessions.

agent: claude-code

Built-in agents:

Agent-specific settings go under agentConfig:

agentConfig:
  permissions: permissionless
  model: claude-sonnet-4-5

permissions accepts:

The legacy value skip is accepted and treated as permissionless.

Choose The Runtime

runtime controls where the agent process runs.

runtime: tmux

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.

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