---
title: Projects
description: "Configure one AO project: agent, runtime, workspace, setup commands, rules, tracker, SCM, and per-role overrides."
---

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:

```yaml title="agent-orchestrator.yaml"
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.

```yaml
agent: claude-code
```

Built-in agents:

| Agent         | Use when                                               |
| ------------- | ------------------------------------------------------ |
| `claude-code` | You want the default, most tested path                 |
| `codex`       | You want OpenAI Codex CLI sessions                     |
| `aider`       | You already use Aider workflows                        |
| `opencode`    | You want OpenCode session discovery and resume support |

Agent-specific settings go under `agentConfig`:

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

`permissions` accepts:

| Value            | Behavior                                              |
| ---------------- | ----------------------------------------------------- |
| `permissionless` | Let the agent edit and run commands without prompting |
| `default`        | Use the agent tool's normal permission behavior       |
| `auto-edit`      | Auto-approve edits, ask for other actions             |
| `suggest`        | Suggest changes without applying them                 |

The legacy value `skip` is accepted and treated as `permissionless`.

## Choose The Runtime

`runtime` controls where the agent process runs.

```yaml
runtime: tmux
```

| Runtime   | Use when                                                                                        |
| --------- | ----------------------------------------------------------------------------------------------- |
| `tmux`    | You want persistent sessions that survive dashboard reloads and can be attached from a terminal |
| `process` | You want a lighter direct process runtime and do not need tmux persistence                      |

Most users should keep `tmux`.

## Choose The Workspace

`workspace` controls how AO isolates each session's code.

```yaml
workspace: worktree
```

| Workspace  | Use when                                                          |
| ---------- | ----------------------------------------------------------------- |
| `worktree` | Default. Fast, disk-efficient, creates a git worktree per session |
| `clone`    | Slower, but gives each session a separate clone                   |

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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
agentRulesFile: AGENTS.md
```

If both are set, AO includes both.

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

```yaml
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:

```yaml
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.

```yaml
tracker:
  plugin: github

scm:
  plugin: github
```

Built-in trackers:

| Plugin   | Purpose       |
| -------- | ------------- |
| `github` | GitHub issues |
| `gitlab` | GitLab issues |
| `linear` | Linear issues |

Built-in SCM plugins:

| Plugin   | Purpose                                  |
| -------- | ---------------------------------------- |
| `github` | GitHub PRs, checks, reviews, merge state |
| `gitlab` | GitLab merge requests                    |

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

```yaml
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`:

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

## Tune Automation Per Project

Project-level reactions override global reaction settings:

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

See [Reactions](/docs/configuration/reactions) for the event list and action behavior.

## Session Recovery

Use these only when you need explicit recovery behavior.

```yaml
orchestratorSessionStrategy: reuse
opencodeIssueSessionStrategy: reuse
```

`orchestratorSessionStrategy` accepts:

| Value           | Behavior                                              |
| --------------- | ----------------------------------------------------- |
| `reuse`         | Attach to the existing orchestrator session           |
| `delete`        | Delete the old session and start a new one            |
| `ignore`        | Leave the old session and start another               |
| `delete-new`    | Delete any newly detected duplicate                   |
| `ignore-new`    | Ignore any newly detected duplicate                   |
| `kill-previous` | Kill the previous session before starting the new one |

`opencodeIssueSessionStrategy` accepts `reuse`, `delete`, or `ignore`.

## Local Reference

These fields are valid in a local project config:

| Field                          | Type       | Purpose                                      |
| ------------------------------ | ---------- | -------------------------------------------- |
| `repo`                         | `string`   | Optional legacy/local repo slug              |
| `defaultBranch`                | `string`   | Branch PRs target, usually `main`            |
| `agent`                        | `string`   | Default worker agent                         |
| `runtime`                      | `string`   | Runtime plugin                               |
| `workspace`                    | `string`   | Workspace plugin                             |
| `tracker`                      | `object`   | Issue tracker plugin config                  |
| `scm`                          | `object`   | Source control plugin config                 |
| `symlinks`                     | `string[]` | Files/directories linked into each workspace |
| `postCreate`                   | `string[]` | Commands run after workspace creation        |
| `agentConfig`                  | `object`   | Agent permissions/model/options              |
| `orchestrator`                 | `object`   | Orchestrator role override                   |
| `worker`                       | `object`   | Worker role override                         |
| `reactions`                    | `object`   | Per-project automation overrides             |
| `agentRules`                   | `string`   | Inline worker instructions                   |
| `agentRulesFile`               | `string`   | Path to a rules file                         |
| `orchestratorRules`            | `string`   | Orchestrator-only instructions               |
| `orchestratorSessionStrategy`  | `string`   | Duplicate orchestrator recovery behavior     |
| `opencodeIssueSessionStrategy` | `string`   | Duplicate OpenCode issue-session behavior    |
| `decomposer`                   | `object`   | Advanced decomposition settings              |

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

<Cards>
	<Card
		title="Reactions"
		href="/docs/configuration/reactions"
		description="Configure what AO does when CI, reviews, or agent state changes need attention."
	/>
	<Card
		title="Remote access"
		href="/docs/configuration/remote-access"
		description="Open the dashboard from another machine without exposing it publicly."
	/>
	<Card
		title="Plugin docs"
		href="/docs/plugins"
		description="Agent, tracker, SCM, notifier, runtime, terminal, and workspace plugins."
	/>
</Cards>
