Apus imports local Claude state through the bundled Claude migration provider. The provider previews every item before changing state and redacts secrets in plans and reports. Standalone apus migrate creates a verified backup; the fresh onboarding path stages the import and publishes it only after verification succeeds.

Onboarding imports require a fresh Apus setup. If you already have local Apus state, reset config, credentials, sessions, and the workspace first, or use apus migrate directly with --overwrite after reviewing the plan.

Two ways to import

Onboarding wizard

The wizard offers Claude when it detects local Claude state.

```bash
apus onboard --flow import
```

Or point at a specific source:

```bash
apus onboard --import-from claude --import-source ~/.claude
```

CLI

Use `apus migrate` for scripted or repeatable runs. See [`apus migrate`](/cli/migrate) for the full reference.

```bash
apus migrate claude --dry-run
apus migrate apply claude --yes
```

Add `--from <path>` to import a specific Claude Code home or project root.

What gets imported

Instructions and memory 
- Project `CLAUDE.md` and `.claude/CLAUDE.md` content is copied or appended into the Apus agent workspace `AGENTS.md`.
- User `~/.claude/CLAUDE.md` content is appended into workspace `USER.md`.
MCP servers 
MCP server definitions are imported from project `.mcp.json`, Claude Code `~/.claude.json`, and Claude Desktop `claude_desktop_config.json` when present.
Skills and commands 
- Claude skills with a `SKILL.md` file are copied into the Apus workspace skills directory.
- Claude command Markdown files under `.claude/commands/` or `~/.claude/commands/` are converted into Apus skills with `disable-model-invocation: true`.

What stays archive-only

The provider copies these into the migration report for manual review, but does not load them into live Apus config:

Apus refuses to execute hooks, trust permission allowlists, or decode opaque OAuth and Desktop credential state automatically. Move what you need by hand after reviewing the archive.

Source selection

Without --from, Apus inspects the default Claude Code home at ~/.claude, the sampled Claude Code ~/.claude.json state file, and the Claude Desktop MCP config on macOS.

When --from points at a project root, Apus imports only that project's Claude files, such as CLAUDE.md, .claude/settings.json, .claude/commands/, .claude/skills/, and .mcp.json. It does not read your global Claude home during a project-root import.

Recommended flow

Preview the plan

```bash
apus migrate claude --dry-run
```

The plan lists everything that will change, including conflicts, skipped items, and sensitive values redacted from nested MCP `env` or `headers` fields.

Apply with backup

```bash
apus migrate apply claude --yes
```

Apus creates and verifies a backup before applying.

Run doctor

```bash
apus doctor
```

[Doctor](/gateway/doctor) checks for config or state issues after the import.

Restart and verify

```bash
apus gateway restart
apus status
```

Confirm the gateway is healthy and your imported instructions, MCP servers, and skills are loaded.

Conflict handling

Apply refuses to continue when the plan reports conflicts (a file or config value already exists at the target).

Rerun with --overwrite only when replacing the existing target is intentional.

Before overwriting a skill generated from a Claude command, Apus backs up its whole directory and records the path in the item's details.backupPath in report.json. That path remains available if the overwrite fails. If the command source cannot be read, migration reports an error without changing the existing skill.

For a fresh Apus install, conflicts are unusual. They typically appear when you re-run the import on a setup that already has user edits.

JSON output for automation

apus migrate claude --dry-run --json
apus migrate apply claude --json --yes

--yes is required for migrate apply outside an interactive terminal; without it Apus errors instead of applying, so scripts and CI must pass --yes explicitly. Preview first with --dry-run --json, then apply with --json --yes once the plan looks right.

Troubleshooting

Claude state lives outside ~/.claude 
Pass `--from /actual/path` (CLI) or `--import-source /actual/path` (onboarding).
Onboarding refuses to import on an existing setup 
Onboarding imports require a fresh setup. Either reset state and re-onboard, or use `apus migrate apply claude` directly, which supports `--overwrite` and explicit backup control.
MCP servers from Claude Desktop did not import 
Claude Desktop reads `claude_desktop_config.json` from a platform-specific path. Point `--from` at that file's directory if Apus did not detect it automatically.
Claude commands became skills with model invocation disabled 
By design. Claude commands are user-triggered, so Apus imports them as skills with `disable-model-invocation: true`. Edit each skill's frontmatter if you want the agent to invoke them automatically.

Related