No single “one command and done”. List installs → back up → remove CK per place → install AgentKit.
If you want to keep custom setup
Preview first, then change. Usually keeps files you customized. Better if you are not ready to remove ClaudeKit fully.
Open gradual migrate guide →You are here
Remove ClaudeKit step by step, then install AgentKit. More steps, cleaner if you want a full switch.
Follow the phases below.
Overview
Complete clean is a pipeline. No supported one-shot command in the audited stable CLIs wipes a whole runtime home or purges CK in one shot.
Close apps/sessions that write the same files; list ck, projects, config folders.
Copy every listed folder to a safe place yourself — may contain secrets; do not share.
Dry-run then apply per scope — repeat per project; --all is not fleet. Stop on legacy / missing metadata.
Installer → doctor --exit-on-fail → explicit login → kit init (no --remote).
Review portable-registry and proven CK-owned artifacts before binary removal / state purge.
Uninstall claudekit-cli via the owning manager; restart sessions; scoped doctor/audit.
00
Unix
command -v ck || true
type -a ck 2>/dev/null || true
ck --version 2>/dev/null || true
ck projects list 2>/dev/null || true
# Preview for THIS cwd + global only (may touch lock state — not a pure read)
ck uninstall --all --dry-run
# Optional fallback if projects list is unavailable:
# cat ~/.claudekit/projects.json 2>/dev/null || trueWindows
Get-Command ck -All -ErrorAction SilentlyContinue
ck --version
ck projects list
# Preview current cwd + global (may touch lock state)
ck uninstall --all --dry-run ck uninstall --all covers only the current project (cwd) plus global — not every registered repo. Prefer ck projects list over raw projects.json. Do not treat dry-run as strictly read-only if lock state can be touched.
Also record custom homes (AGENTKIT_HOME, AGENTKIT_CLAUDE_HOME, CODEX_HOME), aliases/functions, and symlink/reparse points.
01
Unix
set -Eeuo pipefail
umask 077
STAMP=$(date +%Y%m%d-%H%M%S)
DEST=$(mktemp -d "$HOME/agentkit-pre-cutover-backup-$STAMP.XXXXXX")
copy_tree() {
src=$1
name=$2
[ -d "$src" ] || return 0
[ ! -e "$DEST/$name" ] || {
echo "Refusing existing destination: $DEST/$name" >&2
return 1
}
cp -a "$src" "$DEST/$name"
[ -d "$DEST/$name" ] || {
echo "Backup verification failed: $DEST/$name" >&2
return 1
}
}
# Default homes. After inventory, add every other project/custom root before any uninstall.
copy_tree "${AGENTKIT_CLAUDE_HOME:-$HOME/.claude}" claude
copy_tree "$HOME/.claudekit" claudekit
copy_tree "${AGENTKIT_HOME:-$HOME/.agentkit}" agentkit
copy_tree "${CODEX_HOME:-$HOME/.codex}" codex
copy_tree "$HOME/.agents" agents
# Current project if present — repeat copy_tree for each inventoried project path.
copy_tree ".claude" project-claude
copy_tree ".claudekit" project-claudekit
echo "Safety copy completed at: $DEST"Windows
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
$dest = Join-Path $env:USERPROFILE "agentkit-pre-cutover-backup-$stamp-$([guid]::NewGuid().ToString('N').Substring(0, 8))"
if (Test-Path -LiteralPath $dest) {
throw "Refusing existing destination: $dest"
}
New-Item -ItemType Directory -Path $dest -ErrorAction Stop | Out-Null
$items = @(
@{ Src = (Join-Path $env:USERPROFILE '.claude'); Name = 'claude' }
@{ Src = (Join-Path $env:USERPROFILE '.claudekit'); Name = 'claudekit' }
@{ Src = (Join-Path $env:USERPROFILE '.agentkit'); Name = 'agentkit' }
@{ Src = (Join-Path $env:USERPROFILE '.codex'); Name = 'codex' }
@{ Src = (Join-Path $env:USERPROFILE '.agents'); Name = 'agents' }
)
foreach ($item in $items) {
if (Test-Path -LiteralPath $item.Src -PathType Container) {
$target = Join-Path $dest $item.Name
if (Test-Path -LiteralPath $target) {
throw "Refusing existing destination: $target"
}
Copy-Item -LiteralPath $item.Src -Destination $target -Recurse -Force -ErrorAction Stop
if (-not (Test-Path -LiteralPath $target -PathType Container)) {
throw "Backup verification failed: $target"
}
}
}
# Current project if present — repeat for each inventoried project.
if (Test-Path -LiteralPath '.claude' -PathType Container) {
Copy-Item -LiteralPath '.claude' -Destination (Join-Path $dest 'project-claude') -Recurse -Force -ErrorAction Stop
}
if (Test-Path -LiteralPath '.claudekit' -PathType Container) {
Copy-Item -LiteralPath '.claudekit' -Destination (Join-Path $dest 'project-claudekit') -Recurse -Force -ErrorAction Stop
}
Write-Host "Safety copy completed at: $dest"Run in PowerShell (not CMD). This copy is good enough as a safety net; it is not a perfect Windows system backup.
02
# Always dry-run first
ck uninstall --global --dry-run
# Apply only after backup verification + preview review:
# If preview reports legacy mode, missing metadata, or whole-directory removal — STOP.
# Inspect/copy those directories manually first.
ck uninstall --global --force-overwrite -ycd /exact/project/path
ck uninstall --local --dry-run
# Same stop condition: legacy / missing metadata / surprising directory deletes
ck uninstall --local --force-overwrite -y
# Or cwd + global for this directory only (still not the whole fleet):
# ck uninstall --all --dry-run
# ck uninstall --all --force-overwrite -yFiles you created are usually kept. ClaudeKit files you edited are only removed with --force-overwrite. Older installs without a file list: read the dry-run carefully — whole folders may be marked for removal.
Often kept: .gitignore, .repomixignore, .mcp.json, .ckignore, .ck.json, CLAUDE.md (when the install still knows which files were ClaudeKit’s).
ClaudeKit state: config, project list, cache, uninstall recovery copies. It does not go away from ck uninstall alone.
The claudekit-cli package (npm/pnpm/yarn/bun) stays installed. ck uninstall does not remove it — uninstall with the same package manager you used to install.
03
curl -fsSL https://agentkit.best/install.sh | sh
# Windows PowerShell: irm https://agentkit.best/install.ps1 | iex
ak --version
ak doctor --exit-on-fail
# Interactive email/OTP (stable requires an explicit flag)
ak login --email you@example.com
# Or non-interactive (do not paste real keys into chats/screenshots):
# ak login --license-key "$AGENTKIT_LICENSE_KEY" --no-interactive
# ak login --api-key "$AGENTKIT_API_KEY" --no-interactive
# Remote registry is the release default — do not pass --remote
ak kit init engineer --yes --no-interactive
# + marketing kit if licensed
# Optional: global native Claude Code install
# ak kit init engineer --global --yes --no-interactive
# Narrow takeover only: foreign home snapshot, then neutralize .ck.json, statusline.cjs,
# and selected settings residue — not full skills/agents/hooks trees.
# Avoid --no-backup unless you intentionally leave CK residue active. ak kit uninstall / ak uninstall only remove what AgentKit installed —
they do not replace ck uninstall for ClaudeKit cleanup.
On a global Claude Code install, AgentKit may clean a few loose ClaudeKit files (e.g. statusline) — not whole skill/agent trees.
04
# Review portable provenance BEFORE removing the ck binary or purging ~/.claudekit
ls -la ~/.claudekit
ls -la ~/.claudekit/backups 2>/dev/null || true
# Portable ownership/provenance (archive a copy if you may need exact rollback mapping):
# cp -a ~/.claudekit/portable-registry.json "$DEST/portable-registry.json" 2>/dev/null || true
# cat ~/.claudekit/portable-registry.json 2>/dev/null || true
# If you once ran: ck migrate -a codex (project scope default; use -g for global Codex)
# Review only registry-proven CK-owned records under e.g. ~/.codex and ~/.agents/skills.
# Never: rm -rf ~/.claude or rm -rf ~/.codex
# Grace-period state purge (only when rollback is no longer needed):
# Prefer recoverable quarantine of the exact non-symlink path over blind deletion.
# e.g. mv ~/.claudekit "$HOME/claudekit-quarantine-$(date +%Y%m%d)"
# Do NOT copy-paste a blanket rm -rf of shared runtime/state homes.# Review portable provenance BEFORE removing the ck binary or purging state
Get-ChildItem -Force (Join-Path $env:USERPROFILE '.claudekit') -ErrorAction SilentlyContinue
# Get-Content (Join-Path $env:USERPROFILE '.claudekit\portable-registry.json') -ErrorAction SilentlyContinue
# Grace-period: quarantine the exact path (not a recursive force-delete of shared homes)
# $src = Join-Path $env:USERPROFILE '.claudekit'
# $q = Join-Path $env:USERPROFILE ("claudekit-quarantine-" + (Get-Date -Format 'yyyyMMdd'))
# if ((Test-Path -LiteralPath $src) -and -not (Get-Item -LiteralPath $src).LinkType) {
# Move-Item -LiteralPath $src -Destination $q
# }05
type -a ck
# Identify which package manager owns the ClaudeKit install, then run EXACTLY one:
# npm uninstall -g claudekit-cli
# pnpm remove -g claudekit-cli
# bun remove -g claudekit-cli
# Yarn Classic only: yarn global remove claudekit-cli
# Re-enumerate PATH matches after removal
type -a ck 2>/dev/null || true
# Optional AgentKit compatibility entrypoint named "ck":
# Unix often uses a symlink to the ak binary; Windows uses an executable copy.
# Do not delete an intentional AK "ck" entrypoint.Get-Command ck -All -ErrorAction SilentlyContinue
# Run exactly one owning package-manager uninstall for claudekit-cli, then:
Get-Command ck -All -ErrorAction SilentlyContinue
# On Windows an intentional AgentKit "ck" entrypoint is usually a copy of ak, not a symlink.06
ak doctor --json --exit-on-fail
ak doctor --check residual_ck_content
ak doctor --check ck_shim_collision
# Project-native kit install (default after kit init in a project):
ak audit engineer --project-dir . --json
# Claude Code project plugin delivery only:
# ak audit engineer --plugin-mode --project-dir . --json
# Restart old Claude Code / Codex / AK sessions, then confirm in a real session
# that /ck: skills and CK hooks are gone where you expect. residual_ck_content only warns (no auto-fix): it looks for a few leftover ClaudeKit files in an AgentKit-managed Claude home — not a full check of every project, portable install, or alias.
ak doctor --json can still exit 0 when checks look unhealthy; add --exit-on-fail if a script must fail on problems.
Keep your backup for a few days until you are sure you will not undo.