This guide follows the smallest useful AO loop in the desktop app: add one repository, start one worker, watch it work, and review the result.
Install AO, authenticate gh for a GitHub project, and sign in to one supported agent harness. See Installation.
Pick A Safe First Task
Choose a repository where you can create a branch and pull request. Good first tasks have a clear finish line:
- Fix a small bug with a reproducible failure.
- Add one focused test.
- Update a short documentation page.
- Make a narrow refactor with explicit acceptance criteria.
Run The First Session
Add the repository
Open Agent Orchestrator, choose Add project, and select the local repository. The desktop app registers it and keeps the original checkout intact.
Create a worker
Create a new task from the project and enter a short name plus a specific prompt. Select an installed agent harness.
Choose the interface that fits the task:
- Chat for structured conversation, activities, approvals, plans, and durable history.
- Terminal UI for the harness's native interactive terminal.
AO creates an isolated git worktree and branch for the session before launching the selected controller.
Follow the session
Select the session in the sidebar or board. The main pane shows either its Chat conversation or live terminal. The inspector keeps session details, pull-request state, reviews, changed files, and browser preview close at hand.
Activity such as active, idle, waiting for input, blocked, or exited is combined with pull-request facts to derive the status shown by AO.
Give feedback
Use the Chat composer or session message controls for follow-up instructions. Keep corrections concrete:
Keep this change limited to the API route. Do not refactor the shared client.
For a TUI session, the terminal remains available when direct interaction is needed.
Review the pull request
After the worker opens or claims a pull request, AO shows a concise summary of CI, reviewers, unresolved review comments, and mergeability. You can run a reviewer agent, send requested changes back to the worker, resolve comments, or merge when appropriate.
AO never force-deletes a dirty worktree. Cleanup preserves user work when it cannot safely remove a session workspace.
Try A Browser Preview
For a web task, start the app inside the session and select its URL with the optional CLI:
ao preview http://127.0.0.1:5173
If the repository includes .ao/launch.json, ao preview start can start a configured development server. The Browser tab then displays the selected target. AO does not guess a preview target merely because a worker exists.
Try Switching Interfaces
Compatible Claude Code and Codex sessions expose Open Chat or Open Terminal UI. An idle session can switch directly. If a turn is busy, AO asks whether to finish and drain it or stop and interrupt it before replacing the controller. The AO session and worktree remain the same.
Optional CLI
The CLI is a thin client for the app-owned daemon. It is useful for scripting and terminal-first workflows, but is not required for normal desktop use.
ao status
ao session ls
ao send --session <session-id> --message "Run the focused tests before you finish."