Kit installation problems

Diagnose Kit access, source verification, runtime targets, scope, ownership conflicts, and partial installs in a safe order.

Use this page when ak kit init or ak kit install fails before the target runtime can use the Kit.

Confirm the prerequisites

ak --version
ak whoami --json
ak licenses --json

The expected results are the intended CLI version, the intended account, and a grant for the Kit. A successful sign-in without the Kit in ak licenses is an access problem, not an install problem. See Sign-in and Kit access first.

Confirm target and scope

Run the install from the project that should own project-scoped content. Name the runtime explicitly so the destination is unambiguous:

ak kit init engineer --target claude-code
ak kit init engineer --target codex

The default scope is the current project. --global selects the runtime's user scope. Installing successfully in one scope does not make the Kit visible in a different project or user profile.

For Claude Code, project-native delivery is the default. Plugin delivery is a separate choice:

ak kit init engineer --target claude-code --switch-to-plugin
ak kit init engineer --target claude-code --global --switch-to-plugin

The first command selects a project plugin; the second selects a user plugin. Do not add --switch-to-plugin to a Codex install.

For release installs, the authenticated remote registry is the default source. --local is for an explicit development or CI source and requires --kits-dir or AGENTKIT_KITS_DIR; it is not a fallback for a registry failure.

Read the failure class

Result	Meaning	Next action
Exit `1`	You declined the TTY preview, or authentication, download, verification, source, I/O, runtime, or another unclassified operation failed	A preview decline happens before install writes. For any other error, keep the output and inspect the target before retrying.
Exit `2`	Invalid flags, arguments, target, or destination combination	Correct the command; no install recovery is needed.
Exit `3`	A lifecycle action was cancelled, interrupted, or stopped for missing confirmation	Do not treat the code as proof that nothing changed; inspect the reported recovery state.
Exit `4`	Another AgentKit operation holds the Kit lifecycle lock	Let the other install or update finish, then retry. Do not delete the lock file.
Exit `5`	The documented not-found class for a Kit missing from an explicit local `--kits-dir`	Check the Kit name and selected local source; this path can still surface as exit `1` in v2.11.0.
Exit `6`	A refresh cannot detect an installed target, or the command reports an unsafe/conflicting target state	Inspect ownership, delivery mode, scope, and any explicit target requested by the error. An occupied init target can still surface as exit `1`.

Use the error text together with the exit code; v2.11.0 does not attach the more specific class to every missing-source or occupied-target path. A TTY decline or bare Enter also exits 1, but it occurs at the preview gate before source resolution or install mutation. By contrast, a later cancellation or interruption does not guarantee an untouched target: a snapshot, journal, cache entry, or staged write may already exist. Keep any recovery ID and audit the target before retrying.

A Codex install may still succeed while printing Hooks dropped (unsupported on this target). This is a disclosed partial projection, not an exit failure. JSON reports hooksDropped and droppedHookSummaries; review the named event, matcher, and handlers rather than retrying with --force. See Runtime cannot find a Skill or Agent for the supported boundaries.

A separate Capabilities excluded (unsupported on this target) summary means the adapter intentionally omitted an export whose required runtime capability is unavailable. For Engineer on Codex, ak:team is omitted because Codex does not provide the complete Agent Teams lifecycle; ordinary subagents are not used as a fallback. JSON reports capabilityExclusions and capabilityExclusionSummaries. This is expected projection behavior, not a reason to retry the install.

When the target already contains files, do not immediately retry with --force. First determine whether the content is AgentKit-owned, belongs to another install mode, or contains user changes.

Check runtime health and recorded content

ak doctor --adapter claude-code --json
ak doctor --adapter codex --json

Run only the adapter you targeted. Pass one of the documented adapter values: claude-code, codex, or cursor. An unknown --check name is a command error; use ak doctor --list for the names supported by the installed CLI. The claude-code filter also retains shared checks.

Kit integrity and removability checks inspect only directories with positive AgentKit ownership evidence: a matching lifecycle install manifest or AgentKit-authored Claude/Codex plugin metadata. Third-party directories in a shared plugin or Skill root are ignored. Codex integrity accepts both flat and legacy namespace/Kit layouts, but directory shape alone is not ownership proof. Therefore, a no kits installed Doctor row can mean that no attributable AgentKit Kit was found, even when the shared root contains other content.

For Claude Code content, audit the matching delivery mode:

ak audit engineer
ak audit engineer --project-dir .
ak audit engineer --plugin-mode --project-dir ./ak-engineer

The first command audits the user plugin, the second a project-native install, and the third a project plugin whose plugin root is ./ak-engineer. ak audit is read-only: exit 0 is clean; exit 1 means drift or an audit failure; an invalid Kit argument exits 2. Use --strict when a missing or unreadable manifest must also fail the check.

Recover a failed install

Refreshes and overwrite paths use recovery snapshots. If the command prints a snapshot or recovery ID, inspect it before restoring:

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

Only restore after the preview names the state you intend to replace. If an install completed but ak audit proves shipped content drifted, treat its Kit-specific refresh command as a starting point. Audit does not reconstruct the original runtime, scope, or Claude delivery mode: add the matching --target, --global, and, where applicable, --switch-to-plugin selectors before confirming. Do not add --no-backup, change channels, or delete a runtime home as a repair.

Restore is replace-only, preserves unrelated files created later, and is not transactionally all-or-nothing. Review Updates and recovery before applying a snapshot.

Verify the result

Run the adapter-specific doctor check again. Then start a new runtime session in the same project and verify that the expected Skill or Agent is available. If the install is healthy but runtime discovery still fails, continue with Runtime cannot find a Skill or Agent.