Move To The Desktop App
The desktop application is the current, supported distribution. It owns the Go daemon and checks for updates automatically.
The npm package @aoagents/ao is frozen at 0.10.0. It remains available for existing users but will not receive new features or fixes. Do not use npm for a new AO installation.
Preserve active work
Before changing installs, inspect any active sessions and worktrees. Commit, push, or otherwise preserve changes you need. AO will not force-delete dirty registered worktrees, but you should not rely on cleanup as a backup strategy.
Open the desktop build
Download the current desktop application from Installation. Existing npm users may also run:
ao start
The frozen CLI uses this as a bridge to fetch and open the desktop build. It no longer represents the primary product distribution.
Add or import projects
Open the desktop app and add each local repository you want AO to manage. If your installation exposes a legacy import flow, review the projects it finds before accepting them. Do not copy old flat-file session directories over the current database by hand.
Verify your tools
Confirm GitHub and at least one agent harness are still authenticated:
gh auth status
Run the agent harness once outside AO if its sign-in expired, then restart the desktop app.
What Changed Since The npm Product
| Older documentation | Current product |
|---|---|
| Node.js/Next.js orchestrator | Long-running Go daemon with Electron/React desktop UI |
| Global CLI as the main entry point | Desktop app is canonical; CLI is optional and thin |
Flat files under ~/.agent-orchestrator | SQLite and all app state under ~/.ao |
| Stored lifecycle status | Status derived at read time from durable facts |
| Runtime plugin matrix and YAML-first setup | Daemon adapters and project settings through the app/API |
| Browser dashboard on port 3000 | Packaged desktop interface over a loopback daemon |
| Terminal-only sessions | One committed Chat or Terminal UI controller per session |
Old agent-orchestrator.yaml examples and Node plugin packages are not authoritative for the Go rewrite. Reconfigure projects through the desktop app instead of copying unsupported legacy fields.
Data Locations
Current AO state defaults to ~/.ao:
~/.ao/datacontains durable daemon database files.~/.ao/running.jsonadvertises the supervised daemon process and port.- Managed worktrees and AO metadata remain under the AO home.
~/.ao/electroncontains the desktop app's Chromium data.~/.ao/mobile/config.jsoncontains mobile-listener configuration with a hashed password.
Do not delete the old or new data directories until you have inspected and preserved active worktrees.
Updates
Installed desktop builds check for updates on launch and periodically while running. If an update is unavailable through the app, download the latest desktop artifact directly. Running a package-manager update cannot move the frozen npm package beyond 0.10.0.
Historical Package Names
Some very old installations used @composio/agent-orchestrator. Removing that global package is safe once you have moved to the desktop app:
npm uninstall -g @composio/agent-orchestrator
Installing @aoagents/ao is only useful when you intentionally need the frozen legacy bridge.