# ao spawn

Spawn a worker or orchestrator agent session in a registered project, or a standalone worker session that is not tied to a project.
Standalone sessions run in an AO-managed directory. Register a project first with `ao project add` for project-scoped sessions.

## Syntax

```
ao spawn [flags]
```

## Flags

| Flag | Meaning | Default / Required |
|---|---|---|
| `--branch string` | Branch for the session worktree | `ao/<session-id>/root` |
| `--claim-pr string` | Claim an existing PR for authorized implementation continuation. Omit for review-only work | - |
| `--kind string` | Session role: `worker` or `orchestrator` | `worker` |
| `--harness string` | Agent harness to use (see list below) | Project `worker.agent`; required if the project has none |
| `--issue string` | Issue id to associate with the session | - |
| `--model string` | Agent model override for this session only; overrides project/role config | - |
| `--name string` | Display name shown in the sidebar (max 100 characters) | Required |
| `--mode chat\|tui` | Initial session interface; Chat requires harness support | Daemon default, otherwise Terminal UI |
| `--output artifact` | Ask the worker for a file in its artifact directory instead of a PR | Ordinary task |
| `--no-takeover` | Refuse if another active session owns the claimed PR (requires `--claim-pr`) | - |
| `--project string` | Project id to spawn the session in | Optional when `--standalone` is used; defaults to `AO_PROJECT_ID` or the current repo's registered project |
| `--standalone` | Spawn a projectless worker session in an AO-managed directory | Disabled when `--project` is set |
| `--prompt string` | Initial prompt for the agent | - |
| `--skip-agent-check` | Skip CLI readiness warnings; the daemon still validates launch readiness | - |
| `--tracker-provider string` | Issue tracker provider: `github` or `gitlab` | `github` |

`--agent` is an alias for `--harness`.

Available harnesses: `claude-code`, `codex`, `aider`, `opencode`, `opencode-v2`, `grok`, `droid`, `amp`, `agy`, `crush`, `cursor`, `qwen`, `gemini`, `copilot`, `goose`, `auggie`, `continue`, `devin`, `cline`, `kimi`, `muse`, `kiro`, `kilocode`, `vibe`, `pi`, `kimchi`, `prime-agent`, `autohand`, `omp`, `fx`, `unreal-agent`, `mimo-code`, `deepseek-harness`, `openhands`, `command-code`. Check `ao agent ls --refresh` for readiness on the installed build. `unreal-agent` is Chat-only; Gemini, MiMo Code, and OpenHands are Terminal UI-only.

`fx` is experimental and Terminal UI only: spawn it with `--agent fx --mode tui`.

`command-code` is Terminal UI only: spawn it with `--agent command-code --mode tui`.

## Examples

```bash
# Spawn a worker for issue 142 in the agent-orchestrator project
ao spawn --project agent-orchestrator --issue 142 --name "fix-session-leak" --prompt "Fix the session leak described in issue 142. Branch off upstream/main."
```

```bash
# Spawn a worker to continue implementation on an existing PR
ao spawn --project agent-orchestrator --name "continue-pr-88" --claim-pr 88 --prompt "Continue implementation on PR 88."
```

```bash
# Spawn a normal worker to review someone else's PR without taking ownership
ao spawn --project agent-orchestrator --name "review-pr-88" --prompt "Review PR 88 and submit only the requested provider review. Do not claim or attach the PR."
```

```bash
# Spawn an orchestrator using the project's orchestrator configuration
ao spawn --project agent-orchestrator --kind orchestrator --name "coordinate-fix" \
  --prompt "Coordinate the fix and report the worker PR."
```

```bash
# Spawn a standalone worker whose deliverable is an artifact file, not a PR
ao spawn --standalone --agent claude-code --output artifact --name "q3-report" \
  --prompt "Write a one-page summary of Q3 incidents."
```

```bash
# Associate a GitLab issue with a worker
ao spawn --project my-gitlab-app --issue 42 --tracker-provider gitlab \
  --name "fix-issue-42" --prompt "Fix GitLab issue 42."
```