The Agent Orchestrator desktop app is the main control surface. It runs the local daemon, keeps projects and sessions visible, and lets you move between a worker's Chat or terminal, pull-request context, review runs, changed files, and browser preview.
The App Shell
| Area | What it contains |
|---|---|
| Sidebar | Registered projects and their worker or orchestrator sessions. |
| Board / center pane | Sessions grouped by their current derived state. |
| Session view | Structured Chat or the live native Terminal UI. |
| Inspector | Pull request, reviews, files, and browser preview for the selected session. |
AO remembers the session's committed interface mode. Opening a Chat session restores its paged conversation timeline; opening a TUI session reconnects to its terminal through the daemon mux.
Read Session State
AO does not persist a display-status label. It derives what you see from durable facts such as agent activity, termination, controller state, and current pull-request checks, reviews, and mergeability.
Common activity signals include:
- Active — the controller is currently working.
- Idle — it is alive and ready for another instruction.
- Waiting for input — the agent is at an empty prompt and can receive a follow-up.
- Blocked — an approval or permission decision is pending; automation will not inject input.
- Exited — the controller reported that it ended.
A failed or unknown runtime probe alone is not proof that a session is dead.
Work In Chat
Chat sessions show durable messages, provider activities, commands, plans, changed files, approvals, structured questions, usage, and compaction state. History loads in bounded pages so long-running sessions remain responsive.
The composer sends a provider turn through the daemon. A Chat session can also open a session-scoped worktree shell without creating an agent TUI pane.
Work In Terminal UI
TUI sessions preserve the selected harness's native terminal experience. The desktop terminal connects through one daemon WebSocket mux: tmux-backed on macOS/Linux and conpty-backed on Windows.
Use the terminal for native prompts and interactive tools. Use AO's message controls for routine follow-ups so lifecycle reactions can apply the correct delivery policy.
Switch Interfaces
Compatible Claude Code and Codex sessions show Open Chat or Open Terminal UI. AO replaces the controller inside the same session and worktree. If work is in progress, choose whether to let the current turn finish and drain or stop and interrupt it. Progress and recovery state survive daemon restarts.
Pull Requests And Reviews
Once a session has a linked pull request, the inspector shows a concise summary:
- Pull-request identity and link.
- CI state, including failing check names and links.
- Reviewer information and unresolved-review counts.
- Mergeability and reasons the pull request is not ready.
AO can run configured reviewer agents, send review findings back to the worker, resolve review comments, and request a merge. Raw CI logs and full review bodies are not part of the concise desktop summary.
Browser Preview
The Browser tab displays the preview target explicitly selected for the session with ao preview, ao preview <url>, or ao preview start. Each worker receives an isolated ephemeral browser profile, while tabs inside one worker share cookies and web storage.
AO's browser bridge can support agent-driven navigation, snapshots, clicks, typing, screenshots, console inspection, and temporary network-metadata capture. Network capture is off by default, bounded, omits bodies and sensitive values, and expires automatically.
Notifications
The notification center keeps durable alerts for sessions that need input, pull requests ready to merge, merged pull requests, and pull requests closed without merging. Use Unread and All, mark items read, or click through to the relevant session or pull request. Electron also shows app toasts while AO is running.
Connect Mobile
In settings, Connect Mobile enables an authenticated LAN listener and shows pairing details. The mobile app uses the same durable sessions, Chat history, and event stream. It supports Chat by default and can open a TUI session through the authenticated terminal mux.
Connect Mobile is plaintext and intended only for a trusted home network. Turning it off closes the LAN listener.
Project Settings
Project settings configure worker and orchestrator roles without changing the registered repository identity. The desktop app writes through the daemon API; it does not directly edit the database or run session logic in the renderer.
GitHub is the current shipped SCM observation path. Do not expect every tracker or SCM named in historical plugin documentation to be active in the Go rewrite.