Troubleshooting

Confirm you opened the expected AO data home. All state defaults under ~/.ao; an AO_DATA_DIR or AO_RUN_FILE override can point a development launch at a different daemon instance.

Open the desktop app first. Product CLI commands are thin clients and need the app-owned daemon. A stale ~/.ao/running.json is not enough; AO also verifies the recorded process.

The primary daemon uses loopback port 3001 by default and fails fast if it cannot bind. Stop the conflicting local process or use a deliberate development AO_PORT override. Never change the bind host to expose the daemon.

Leave the app open briefly so its SSE connection can reconnect and invalidate current queries. If it does not recover, restart the desktop app. The event stream supports replay, but a full app restart is the safest user-level recovery.

Install the harness, run it once to authenticate, and restart AO. The desktop daemon inherits a login-shell environment and reuses each provider's installed binary and authentication.

Confirm the selected harness supports native Chat and its binary is authenticated. Chat currently supports Codex, Claude Code, OpenCode, and Droid. Choose Terminal UI when the harness lacks Chat support or preflight cannot connect.

Run tmux -V and install tmux if it is missing. On Windows, AO uses its native conpty host instead.

Open the session and answer the pending approval or permission prompt. AO deliberately does not inject lifecycle messages while a controller is blocked.

Status is derived from activity, termination, controller, and pull-request facts. A failed runtime probe is not treated as death. Reopen the session and inspect its Chat or terminal before killing it.

Use the desktop restore action or ao session restore <session-id>. Restore reuses the same session and worktree when the selected adapter supports recovery. Check that the harness remains installed and authenticated.

Run gh auth status and confirm the active account can access the repository. GitHub authentication is lazy so an auth failure does not need to block unrelated local session work.

Claim it from the session UI or, inside the worker, run ao session claim-pr <pr-number-or-url>; AO reads the worker from AO_SESSION_ID. From another shell, use ao session claim-pr <session-id> <pr-number-or-url>.

The SCM observer polls GitHub and respects rate limits and ETags. Check gh auth status, wait for another observation cycle, and open the pull request directly for full raw logs or comment bodies.

Open the review run and use its send action. Reviewer execution and delivery are separate operations so you can inspect findings before changing the worker conversation.

Select a target explicitly with ao preview <url>, or use ao preview start when the worktree contains a valid .ao/launch.json. AO does not auto-discover a preview for every new worker.

Run ao preview start <configuration> and inspect the returned error. Verify the command and working directory in the session's .ao/launch.json, then run the same command in its worktree shell.

Select the correct session and browser tab. Browser profiles are isolated per worker, and commands are authorized for the selected session only.

Confirm Connect Mobile is still enabled, both devices are on the same trusted LAN, and the phone used the current connection password. Rotating the password disconnects the previous phone.

The QR carries the host and port, not the password. Rotate the connection password in desktop settings if the pairing details or password may have been exposed.

Do not. Transport is plaintext HTTP by deliberate design. Use it only on a trusted home network, and disable it when finished.