---
title: Quickstart
description: Start AO, spawn one worker session, and follow it from task to pull request.
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Step, Steps } from "fumadocs-ui/components/steps";

This quickstart walks through the smallest useful AO loop: start the dashboard, create one worker session, watch it work, and clean it up after the PR is merged.

<Callout type="info" title="Before you start">
  Complete [Installation](/docs/installation) first. You need `ao`, Git, one authenticated source-control CLI such as `gh`, and one signed-in agent CLI.
</Callout>

## Pick A Safe First Task

Use a repository where you can push a branch and open a pull request. For the first run, choose a task that is easy to review:

- Fix a small bug with a clear failure.
- Update a short documentation page.
- Add a narrow test.
- Make a small refactor with obvious acceptance criteria.

Avoid broad tasks like “improve auth” or “clean up the app.” AO can run many agents, but each worker still needs a task with a visible finish line.

## Run The First Session

<Steps>
<Step>

### Start AO

From the repository you want AO to manage:

```bash
cd ~/code/my-repo
ao start
```

On the first run, AO creates `agent-orchestrator.yaml`, starts the dashboard, and starts an orchestrator session for the project. The dashboard URL is printed in the terminal, usually `http://localhost:3000`.

Keep this terminal running. It owns the dashboard and lifecycle polling.

</Step>
<Step>

### Spawn one worker

Open a second terminal in the same repository.

<Tabs items={["GitHub issue", "Freeform prompt"]}>
  <Tab value="GitHub issue">
  ```bash
  ao spawn 42
  ```

  Replace `42` with the issue number. AO fetches the issue through `gh`, creates a worktree, starts the configured worker agent, and gives it the issue context.
  </Tab>
  <Tab value="Freeform prompt">
  ```bash
  ao spawn --prompt "Update the README install section to mention Node 20"
  ```

  Use this when the task is not tracked in GitHub, GitLab, or Linear yet. Keep the prompt specific and reviewable.
  </Tab>
</Tabs>

The command prints the session id and dashboard URL. Session names use the project prefix, for example `myrepo-1`.

</Step>
<Step>

### Watch the dashboard

Open the session card. You should see:

- The worker activity state: active, ready, idle, waiting for input, blocked, or exited.
- The worktree path and branch name.
- The live terminal output.
- The PR link after the agent creates one.
- CI and review state after a PR exists.

Use `ao status` when you want the same high-level view in a terminal:

```bash
ao status
```

</Step>
<Step>

### Intervene only when needed

AO routes routine feedback back to the worker:

- CI failure: AO sends failure context to the session.
- Requested changes: AO sends the review feedback to the session.
- Merge conflicts: AO can ask the worker to rebase or resolve the conflict.
- Agent stuck or waiting for input: AO notifies you.

If you need to give the worker a direct instruction, use `ao send`:

```bash
ao send myrepo-1 "Keep the fix smaller. Do not refactor the API layer."
```

Use `ao send` instead of raw terminal input. It preserves AO's busy detection, retry handling, and message formatting.

</Step>
<Step>

### Review and merge

When the PR is green and ready, review it like any other pull request. AO does not merge by default.

After the PR is merged or the issue is closed, clean up completed sessions:

```bash
ao session cleanup --dry-run
ao session cleanup
```

</Step>
</Steps>

## What AO Created

| Item | What it means |
| --- | --- |
| `agent-orchestrator.yaml` | Project config: plugins, projects, reactions, runtime, and notifier choices. |
| Orchestrator session | A coordinating session started by `ao start`; it supervises worker sessions. |
| Worker session | The agent process that works on one issue or prompt. |
| Worktree | An isolated checkout for the worker's branch. |
| Session metadata | Files under `~/.agent-orchestrator/...` that let AO track branch, PR, status, and runtime state. |

## If Something Looks Wrong

| Symptom | First check |
| --- | --- |
| Dashboard is not updating | Make sure the `ao start` terminal is still running. |
| `ao spawn` warns that AO is not running | Start AO with `ao start` before spawning. |
| GitHub issue or PR data is missing | Run `gh auth status` and check the `repo` field in `agent-orchestrator.yaml`. |
| Agent started but does nothing | Open the session terminal and send a clear instruction with `ao send`. |
| Windows spawn fails with tmux errors | Set `defaults.runtime: process` in `agent-orchestrator.yaml`. |

## Next

<Cards>
  <Card title="Parallel issues" description="Spawn several worker sessions without duplicating active work." href="/docs/guides/parallel-issues" />
  <Card title="CI recovery" description="See how AO reacts when checks fail." href="/docs/guides/ci-recovery" />
  <Card title="Configuration" description="Tune agents, runtimes, projects, reactions, and notifiers." href="/docs/configuration" />
  <Card title="Dashboard" description="Understand session cards, attention zones, and live terminal views." href="/docs/dashboard" />
</Cards>
