The desktop app is the canonical install path. It owns the local daemon, requires no global ao command, and checks for updates after launch and while it is running.
Prerequisites
| Tool | When you need it | Why |
|---|---|---|
| Git | Always | Creates and manages isolated worktrees and branches. |
GitHub CLI gh | GitHub projects | Uses your existing authentication for repository and pull-request operations. |
| An agent harness | Always | The coding agent AO launches, such as Claude Code, Codex, Cursor, Aider, or OpenCode. |
| tmux | Terminal UI on macOS/Linux | Keeps native TUI sessions attachable. Chat does not require an agent tmux pane. |
AO uses the agent binaries and sign-ins already installed on your machine. It does not bundle Claude Code, Codex, or other provider CLIs.
Set Up AO
Install and open the desktop app
Choose the download for your platform above, install it, and open Agent Orchestrator. The app starts and supervises the local Go daemon automatically.
Authenticate GitHub
For a GitHub repository, sign in with the GitHub CLI:
gh auth login
gh auth status
Use an account that can read the repository and perform the branch and pull-request actions you expect the agent to take.
Install and sign in to an agent
Install at least one supported agent harness and run it once outside AO to complete its sign-in flow. AO detects available harnesses when you create a session.
For structured Chat, start with Claude Code, Codex, OpenCode, or Droid. Other supported harnesses run through their native Terminal UI.
Add a project
In the desktop app, choose Add project and select an existing local git repository. AO registers the project without moving your original checkout. New worker sessions receive their own isolated worktrees.
Legacy npm CLI
Already have the npm CLI?@aoagents/ao is frozen at 0.10.0 and is no longer recommended.
0.10.0 is the final npm release. The package remains a legacy bridge for existing users and will not receive new product features. Running ao start from that install fetches and opens the desktop build.
npm install -g @aoagents/ao
ao start
New users should install the desktop app directly instead.
Where AO Stores Data
All AO application state lives under ~/.ao by default, including the daemon database, run file, managed worktrees, Electron browser data, and mobile pairing configuration. Advanced installations can override daemon paths with AO_DATA_DIR and AO_RUN_FILE.
Common Installation Problems
No agent is available
Install a supported agent harness, run it once to authenticate, then restart AO so the desktop-launched daemon receives the updated login-shell environment.
GitHub data is missing
Run gh auth status. Confirm the active account can access the repository and its pull requests.
Terminal UI cannot start on macOS or Linux
Install tmux, or choose Chat when the selected harness supports it.
The legacy `ao` command is not found
The desktop app does not require it. Only troubleshoot the package manager's global bin path if you intentionally use the frozen legacy CLI.