Configuration

AO uses configuration in two layers:

• Global registry — remembers which projects AO knows about and which repository each project points to.
• Local project config — controls behavior for one project: agent, runtime, workspace, rules, reactions, tracker, SCM, and setup commands.

Most users should let ao start create the registry entry, then edit the local agent-orchestrator.yaml in the project when they want to change behavior.

What AO Creates

When you run AO in a repository, it can register the project globally and create a local config file:

ao start

The global registry lives at:

~/.agent-orchestrator/config.yaml

That file is AO-owned. It stores durable identity:

projects:
  my-app:
    projectId: my-app
    path: /Users/me/code/my-app
    storageKey: generated-by-ao
    repo:
      owner: acme
      name: my-app
      platform: github
      originUrl: git@github.com:acme/my-app.git
    defaultBranch: main
    sessionPrefix: app

The local project config lives inside the repository:

my-app/agent-orchestrator.yaml

That file is for behavior:

agent: claude-code
runtime: tmux
workspace: worktree

symlinks:
  - .env
  - .claude

postCreate:
  - pnpm install

agentRules: |
  Run tests before pushing.
  Keep PRs small and focused.

What To Edit

Do not manually edit storageKey, path, or originUrl unless you are repairing a broken registry entry and already know why it is wrong.

Local Project Config

A practical local config usually starts with the agent, runtime, workspace, setup, and rules:

agent: claude-code       # claude-code | codex | aider | opencode
runtime: tmux            # tmux | process
workspace: worktree      # worktree | clone

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

symlinks:
  - .env

postCreate:
  - pnpm install

agentRules: |
  Use pnpm, not npm.
  Run pnpm test before opening a PR.

See Projects for the full project behavior reference.

Global Defaults

You can set defaults that apply across all registered projects in the global registry:

defaults:
  agent: claude-code
  runtime: tmux
  workspace: worktree
  notifiers: [desktop]

notificationRouting:
  urgent: [desktop, composio]
  action: [desktop]
  warning: [composio]
  info: [composio]

Project-local values override global defaults.

Config Lookup

AO resolves configuration in this order:

1. AO_CONFIG_PATH, if set.
2. agent-orchestrator.yaml or agent-orchestrator.yml found by walking upward from the current directory.
3. The global registry path.
4. Legacy home-directory fallbacks:
   • ~/.agent-orchestrator.yaml
   • ~/.agent-orchestrator.yml
   • ~/.config/agent-orchestrator/config.yaml

For normal use, run AO from inside the repository and keep agent-orchestrator.yaml in the repo root.

Top-Level Global Keys

Where Data Lives

AO stores runtime data under ~/.agent-orchestrator/ by storage key. Session files, archived sessions, feedback reports, and observability snapshots are plain files so they can be inspected during debugging.

You usually do not need to configure this. If you need to debug a session, start with:

ls ~/.agent-orchestrator

Next Steps