---
title: Migration
description: Breaking changes between AO versions and how to upgrade cleanly.
---

import { Callout } from "fumadocs-ui/components/callout";

<Callout type="info">
  AO is in active development and follows semver pre-1.0. Breaking changes are called out here with migration steps.
</Callout>

## From `@composio/agent-orchestrator` to `@aoagents/ao`

The npm scope moved to `@aoagents/ao`. If you installed under the old name:

```bash
npm uninstall -g @composio/agent-orchestrator
npm install -g @aoagents/ao
```

Your config and data directory (`~/.agent-orchestrator`) don't change — no data migration needed. GitHub org and repo URLs (`ComposioHQ/agent-orchestrator`) didn't change either.

## `ao spawn <project> <issue>` → `ao spawn <issue>`

The old two-argument form is rejected with an error. Pick the project via `-p` or by running from inside its worktree:

```bash
# old
ao spawn myproject 42

# new
ao spawn 42 -p myproject
# or, from inside the project's worktree:
ao spawn 42
```

## `ao init` → `ao start`

`ao init` has been removed. Use `ao start` instead; it auto-creates `agent-orchestrator.yaml` on first run and opens the dashboard in one step.

## Upgrading

Preferred:

```bash
ao update
```

The command detects your install method (`npm-global`, `pnpm-global`, git, or unknown) and picks the right upgrade path. Override behaviour with `--skip-smoke` or `--smoke-only` for git installs.

## Before major upgrades

1. `ao status` — see what's running.
2. `ao session cleanup` — archive finished sessions.
3. `ao stop --all` — halt every AO instance.
4. Upgrade.
5. `ao doctor` on the new version.