Updates and recovery

Use this page when an update does not apply, updates the wrong scope, reports a partial failure, or needs to be rolled back.

Identify what you intended to update

ak self-update handles the ak binary. ak update coordinates the CLI, global Kits, and project Kits, or updates an explicitly selected scope. ak kit refresh refreshes one installed Kit route independently.

Check the binary without changing disk:

ak --version
ak self-update --check --channel <channel> --json

A successful check exits 0; read available, status, and version fields to learn whether an update exists. Network, verification, staging, or replacement errors exit 1; invalid flags exit 2. A package-manager-owned binary reports the manager and its native upgrade command instead of replacing the binary. Binary-update and Kit-package channels are separate. Check the intended binary channel and select the same intended Kit channel explicitly when compatibility requires them to align; do not edit cached manifests.

Preview Kit and project changes

ak update ./myproj --dry-run --show-diff

An explicit project --dry-run is read-only and exits 0 when the preview succeeds. In a script or non-interactive session, ak update ./myproj without --yes also stays preview-only, but exits 3 so automation can distinguish “not applied” from an applied update. Bare interactive ak update opens the CLI → global Kits → project Kits wizard; each apply step defaults to No.

Apply only after checking the selected project, runtime, Kit, and channel:

ak update ./myproj --yes

Use ak self-update --yes for the binary only, or ak update --global --yes for AgentKit-owned user installs. Bare ak update --yes accepts every unified wizard step, so use it only when all three scopes are intended.

Global Kit update is preserve-only: --force does not authorize overwriting user-modified global files. A Claude user-plugin-only install is reported rather than silently refreshed; refresh that exact route with:

ak kit refresh <kit> --global --switch-to-plugin --yes

If a global Claude refresh reports refusing foreign-home takeover, it stopped before changing the discovered Claude home. A snapshot ID can still be present because the snapshot is captured before that ownership refusal; it proves that recovery material exists, not that a partial write occurred. Confirm the home is the intended global install, then run the exact ak kit init <kit> --global command from the error to re-establish ownership. Do not restore solely because this pre-mutation failure includes a snapshot.

An applied runtime error, CLI hard gate, partial Kit failure, or interruption after mutation exits 1. Invalid scope or target combinations exit 2.

Work around one failed global runtime on Windows

A global update reports each runtime separately. If the Claude Code row failed before mutation while the Codex row says updated, Codex was updated; do not describe the whole update as failed.

Do not treat generic terminal guidance about disk space or backup permissions as the root cause. Current guidance uses that classification for any raw error that contains snapshot. A printed snapshot ID proves that at least one earlier capture succeeded. It does not prove a partial write, and a later capture can still fail because of disk space, ACL or security software, a locked or unreadable Claude path, a foreign-home refusal, or another snapshot-path error.

Read the local detail first

In PowerShell, locate the failed Claude Code row and its relevant markers in the newest local report:

$report = Get-ChildItem "$env:USERPROFILE\.agentkit\support\update-report-*.md" |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 1

$report.FullName
Select-String -Path $report.FullName `
  -Pattern '^### engineer \[claude-code\]$','^- Detail:','^- Snapshot:'

Share only the relevant - Detail: and - Snapshot: lines. Redact usernames, email addresses, project paths, tokens, and unrelated diagnostics. Without the raw - Detail:, keep the cause unresolved.

If more evidence is needed, these checks are read-only:

ak backups show <snapshot-id> --json
ak backups verify <snapshot-id>
ak doctor --json --offline
Get-PSDrive -Name C

Fix the exact cause, then retry only Claude Code

Keep .agentkit, .claude, and the snapshot. Do not bypass the safety boundary with --no-backup.

• For a locked or unreadable path, close Claude Code and the process holding that path, correct readability or permissions for that exact path, then retry.
• For a no-space detail, free space on the volume that contains the source and AgentKit backups.
• For refusing foreign-home takeover, first confirm that AgentKit should own the global Claude Code surface. Then use the exact recovery command ak kit init engineer --global. This is an ownership decision, not a permissions error.

After correcting the cause, retry only the failed runtime:

ak update --global --target claude-code --yes

At the time this behavior was verified, 2.8.0-beta.8 was the latest beta. In that version, a refusing foreign-home takeover detail should receive the dedicated pre-mutation ownership guidance above. If that exact detail instead receives generic snapshot guidance, preserve the redacted report lines and contact support; treat it as a guidance regression, not proof of a snapshot or permissions failure.

A Codex warning such as preserving hook script ...cook-after-plan-reminder.cjs is a separate ownership-preservation result. Do not use it to diagnose the Claude Code snapshot failure.

Check the result

ak --version
ak doctor --json
ak audit --project-dir . --json

The CLI version and doctor report confirm binary and environment state. Audit checks recorded project-native Claude Code Kit content here; use ak audit --json for user plugins or --plugin-mode --project-dir ./ak-engineer for the named project plugin root. Exit 0 is clean and exit 1 means drift or an audit error. Remember that default doctor output can be unhealthy while the command exits 0; inspect data.healthy.

Inspect recovery snapshots

Mutating project and global Kit update paths take recovery snapshots. Binary self-update instead uses verified replacement. Use the snapshot ID printed by the failed Kit operation when available:

ak backups list
ak backups show <id>
ak backups verify <id>
ak backups restore <id> --dry-run

list, show, verify, and restore preview are read-only. show or verify exits 5 if the ID does not exist; verify exits 1 if the snapshot is corrupt. Do not restore a snapshot that fails verification.

Project update output can say that its snapshot is outside ak backups restore scope and print a snapshot-files directory. In that case, follow the printed manual copy path for the affected project files; do not try to widen restore authority or restore unrelated state.

Restore a verified snapshot

Preview first, then confirm the exact ID:

ak backups restore <id> --dry-run
ak backups restore <id>

If ak backups show <id> lists project bundle roots, authorize only those exact absolute paths with one repeated --allow-root per root:

ak backups restore <id> --allow-root /absolute/project

A broader or different path is rejected.

Use --latest only after ak backups list proves the newest snapshot belongs to this operation. Restore exit behavior is classified:

Restore is replace-only: it overwrites captured files, removes exact paths recorded absent and explicitly approved AgentKit plugin trees, and preserves unrelated files created later. A multi-file restore is not transactional, so a host failure can leave an intermediate state; avoid interrupting it and take an appropriate backup before rolling backward when practical.

After restore, repeat ak --version, ak doctor --json, and the applicable audit. Do not delete backup storage, runtime homes, or ~/.agentkit; those actions remove the evidence and recovery path you need. Do not use --force as a routine update retry.

Related pages

• Updating ak
• Installation problems
• Kit installation problems