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 --channel <channel>
ak kit init engineer --target codex --channel <channel>
ak kit init engineer --target grok --channel <channel>
ak kit init engineer --target pi --channel <channel>
ak kit init engineer --target omp --channel <channel>

Replace <channel> with the release channel selected in the docs header. Omitting --channel on ak kit init uses persisted kit.channel when that key is set; otherwise it resolves stable and can return version_not_available for a target available only on another channel. 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 --channel <channel>
ak kit init engineer --target claude-code --global --switch-to-plugin --channel <channel>

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

For released targets, 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. --target grok uses the signed Grok registry package by default. Add --local --kits-dir only for an explicit development or CI source; do not use local source as a fallback for a registry failure.

A native Pi project install writes below <project>/.pi/{skills,agents,rules,extensions}. A Pi global install writes directly below the active PI_CODING_AGENT_DIR or ~/.pi/agent profile. A fresh install refuses an occupied profile by default; retry with --force only after reviewing the occupied paths and deciding to authorize the overwrite. Pi installs do not provide ak run --target pi and do not write .pi/commands/.

If the trusted project also contains a matching Codex Skill under .agents/skills/, a Pi install warns about which copy takes precedence. Project .pi/skills/ wins for a project Pi install; the trusted project's .agents/skills/ copy wins over a global Pi profile copy. The warning does not delete or rewrite either Skill.

OMP projects portable Skill directories and top-level SKILL.md names as ak-<slug> without rewriting body aliases such as /ak:cook or $ak:cook. ak run <kit>/<skill> --target omp keeps the same dispatch selector. Trusted project OMP also discovers project .agents/skills. On a same-name collision, project .omp/skills shadows project .agents/skills for a project OMP install; project .agents/skills shadows the OMP profile copy when a global OMP install is used from that project. Both ak kit init and ak kit install warn and continue without skipping OMP emission, changing either Skill, .agents, or OMP settings. This is not exit 6 and does not require --force.

A native Grok project install writes below <project>/.grok and records lifecycle ownership below <project>/.agentkit/adapters/grok/<kit>. A global install uses ${GROK_HOME:-~/.grok} and ${AGENTKIT_HOME:-~/.agentkit}/adapters/grok/<kit>. This is separate from Grok scanning .claude/settings.json in Claude-compat mode. Native project Hooks do not run until you explicitly trust the project in Grok.

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 Hook groups not projected. 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 a named export whose required runtime capability is unavailable. JSON reports capabilityExclusions and capabilityExclusionSummaries; inspect those names instead of assuming another Skill was excluded. The Engineer Codex projection includes ak:team, but using it still requires a live team lifecycle and must stop rather than substitute ordinary subagents when those capabilities are unavailable.

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.

For global Codex Hooks, do not treat every link as interchangeable. Only the final hooks leaf may point to the resolved user's canonical ~/.codex/hooks, as a POSIX symlink or a Windows directory junction; linked parents and other targets are refused. Resolve the path mismatch instead of retrying with --force.

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 that the installed CLI lists for Doctor; this release documents claude-code, codex, or cursor for adapter-specific checks. If a Grok-specific Doctor filter is not available in the installed CLI, inspect the install summary, native roots, and Grok discovery instead. 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 where one exists. For Pi, start a fresh Pi session in the same project or active global profile, then verify .pi/skills/ak-<slug>/SKILL.md, .pi/agents/, and .pi/extensions/ instead of looking for .pi/commands/. For Grok, start a new session in the same project, trust project Hooks if applicable, and verify discovery below .grok. Then confirm 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.

hooksDeferred is a subset of hooksDropped: the harness bridge defers that subscription, which does not mean the runtime cannot express it. Read the summary to distinguish deferred from unsupported groups.