155 lines
5.2 KiB
Plaintext
155 lines
5.2 KiB
Plaintext
---
|
|
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>
|