ak kit init

Use ak kit init when you want to resolve a kit and emit its capabilities into a runtime or build directory. Choose the target, scope, and delivery mode before you run it, because those choices determine both network activity and disk effects.

Choose the correct lifecycle command

Use ak kit refresh, not a fresh forced install, when your goal is to update an existing route.

Before you start

Released kits use the authenticated remote registry by default. The channel resolves in this order: an explicit --channel, then the channel recorded in the install receipt of an existing destination, then kit.channel, then stable. An explicit --channel applies to that request only and is not saved; it does not change later ak kit init, ak kit refresh, or ak update runs. Conflicting receipts print a warning, fall through to kit.channel, and are never rewritten. Paid kits require a valid CLI session and entitlement before preview or writes.

ak whoami
ak licenses

Remote resolution can renew local authentication state, contact the registry, download a runtime-specific artifact, and populate the verified cache. A warm, fully verified cache can satisfy some offline failures; a cold or unverifiable cache fails closed.

Use --local --kits-dir <dir> only for an explicit development or CI source. It is not a fallback for failed authentication or entitlement.

Usage

ak kit init <kit-name>

Supply one installable kit name in scripts. On an interactive TTY, omitting the name can open the setup wizard; a scripted invocation without the name fails.

For remote examples, replace <channel> with the release channel selected in the docs header. Omitting --channel uses the existing receipt channel, then kit.channel, then stable.

Command flags

--skills, --exclude-skills, and --select-skills are alternative selection modes. --select-skills requires an interactive terminal. Shared flags are listed in CLI conventions.

Choose a target, scope, and mode

A project install refuses a route that resolves to the user-level install, such as a project directory that is your home directory, a project .agentkit that is your AgentKit home, or a project .claude, .codex, or Pi extension that is the matching user-level root. The check covers every selected target, runs before any Skill picker, preview, lock, snapshot, or write, and exits 6. Re-run with --global to manage the user-level install, or run from another project directory. Build and export routes are not checked.

Project and user installs can coexist. Claude native and plugin delivery are separate modes within a scope; switching modes is an explicit, snapshot-backed transition. Codex does not provide full Claude command, Hook, or status-line parity, so review emitted warnings instead of assuming every component was projected.

For global Codex Hooks, an established wrapper may alias only the final hooks leaf to the resolved user's canonical ~/.codex/hooks, using a POSIX symlink or a Windows directory junction. AgentKit uses that canonical path for commands, writes, rollback, and ownership. Linked parents and leaves that resolve to any other target are rejected.

portable is export-only. --target portable without --out exits 1 before preview, confirmation, source resolution, lifecycle preflight, or disk writes:

init: target "portable" is export-only and has no install mode; re-run with --out DIR to export a standalone build

--out alone preserves the remote source default and reports mode: "build" in JSON. Explicit --build-only --out remains valid and selects the local-development source default. Add --zip when a portable export should also produce one uploadable ZIP per Skill. Portable writes no install record. AGY is global-only and is not a refresh lifecycle peer. Pi is an install projection target, not an ak run adapter; use Pi's own discovery for emitted .pi/skills and do not substitute --target omp unless you intend Oh My Pi dispatch.

OMP projection uses portable ak-<slug> directories and top-level name: ak-<slug> in projected SKILL.md files. It does not rewrite body aliases such as /ak:cook or $ak:cook, and ak run <kit>/<skill> --target omp keeps its dispatch selector. In a trusted project, project .omp/skills shadows a colliding project .agents/skills copy for project-scope OMP installs; project .agents/skills shadows the OMP profile copy for global installs used from that project. ak kit init --target omp warns and continues without skipping OMP emission, deleting or rewriting either Skill, altering .agents or OMP settings, requiring --force, or returning exit 6.

Review confirmation behavior

On an interactive TTY, install mode prints a destination preview and asks Continue? [y/N]:. Bare Enter or any answer other than y or yes declines.

A TTY decline currently exits 1, not 3. Build and export routes do not show the install preview because they write to the selected output directory rather than an install destination.

For intentional automation, specify the route and confirmation explicitly:

ak kit init engineer --target codex --yes --no-interactive --json --channel <channel>

# Grok project install from an explicit local development source.
ak kit init engineer --local --kits-dir ./kits --target grok --yes

# Grok user install from the same explicit local source.
ak kit init engineer --local --kits-dir ./kits --target grok --global --yes

# Portable export with one uploadable ZIP per Skill.
ak kit init engineer --target portable --out ./ak-export --zip

Understand disk effects

An install can write runtime-native files, AgentKit ownership and lifecycle metadata, project configuration, Hook scripts, native skill directories, and mode-transition records. A global Codex install can also register the AgentKit MCP runtime in the user Codex configuration.

Unknown and user-modified files are preserved unless a supported operation and explicit --force authorize a bounded overwrite. Before destructive refresh or mode-transition writes, AgentKit normally creates recovery snapshots. Do not use --no-backup for routine installation.

Reset one target with --fresh

ak kit init <kit> --fresh resets one selected install target to kit-only output. A target is one kit, one runtime, and one scope. Use it when the kit's own lifecycle root has collected custom or stale files that a refresh or --force keeps. ak kit install accepts the same flag.

# Review the plan; a scripted run stops here with exit 3.
ak kit init engineer --fresh --target codex

# Reset after reviewing the plan.
ak kit init engineer --fresh --target codex --yes

The reset runs in this order:

1. Build a read-only plan. It lists the kit-exclusive reset root, the existing files there, the custom or unrecorded files it removes, the recorded files whose local edits it discards (inside and outside the reset root), the links and special files it keeps, the shared runtime roots it does not reset, and any safety risks.
2. Ask for consent once (see below).
3. Rebuild the plan under the lifecycle lock. If the safety risks changed, ask again on a TTY or stop with exit 3 in a scripted run.
4. Snapshot every path the reset can delete or overwrite, then verify each snapshot. A snapshot that fails verification is retaken once.
5. Emit the kit.
6. Sweep leftover files inside the reset root. A file changed since the plan was built is kept. This kit's stale recorded files are removed even when they were modified, because the verified snapshot holds their bytes.

What the reset leaves alone:

• Shared runtime roots, such as .claude or ~/.codex, change only through this kit's recorded files, as they would under --force.
• Sibling kits, other runtimes, and the other project or global install are not reset.
• Links, junctions, reparse points, and special files inside the reset root are kept and never followed.
• The previous skill selection is not inherited. The whole kit is installed unless you pass --skills, --exclude-skills, or --select-skills.

For Codex, an [agents.<slug>] table that points to a removed agent file is pruned, so no dangling config_file entry remains.

Consent and safety risks

--yes alone never accepts a risk. A plan lists a risk for each check it cannot prove:

• unproven-ownership: the occupied reset root has no install manifest, or the manifest is unreadable.
• other-kit-ownership: the reset root's install manifest names another kit.
• snapshot-unverified: the recovery snapshot failed verification twice. Nothing is reset until you accept it.

The risk token covers the exact risk kinds, paths, and files of that plan for that kit and target. For an other-kit-ownership risk it also covers the kit that owns the root, so accepting one kit's record never covers another kit's. A new risk, file, or owning kit changes the token. If the locked plan has fewer risks than you accepted, the reset proceeds. A token passed to a plan with no risks is ignored with a notice. A token that accepts an unverified snapshot keeps accepting one for that target, so do not save it for later runs. --accept-risks without --fresh exits 2.

With --json, a stopped run writes an envelope with kind=kit.init_fresh_plan and status: "confirmation-required". Its data includes reason (not-confirmed, risks-not-accepted, risks-changed, or snapshot-unverified), resetRoots, notReset, unrecordedPaths, modifiedRecordedPaths, modifiedOutsidePaths, keptLinks, risks, riskToken, confirmWith, and command. Each risks entry has kind, path, detail, effect, and files, plus owner for an other-kit-ownership risk. Human output caps each path list at 25 entries; the JSON plan carries the complete lists.

Automatic adjustments

• pi, grok, omp, and dsh keep kit output and runtime files in one folder, so no kit-only boundary exists. A fresh request there runs a snapshot-backed --force refresh instead, prints a notice, and keeps custom files.
• A reset root reached through a link or reparse point also falls back to the snapshot-backed --force refresh with a notice.
• A Claude Code plugin install is reset in place in plugin mode, even when --switch-to-plugin is omitted.
• A Codex install that still uses the legacy skills layout is migrated first with a snapshot-backed --force refresh, then reset in the same command.

Refusals

These exit 2 before the reset touches anything:

• --fresh with --force, --no-backup, --build-only, or --out.
• More than one target.
• An export-only target such as portable.

These exit 1 before any mutation:

• A pending native-to-plugin switch. Finish it with ak kit init <kit> --switch-to-plugin, then run --fresh.
• A pending legacy migration transition. Run ak migrate rollback first.
• Recorded ownership evidence that cannot be read.
• A global Claude home that is not AgentKit-owned. Run ak kit init <kit> --global to establish ownership first.
• An ambiguous boundary, such as a runtime root inside the reset root, or a reset root that is not a directory.
• A snapshot that cannot be taken.

A project route that resolves to the user-level install, such as a project directory that is your home directory, exits 6 before the plan is built. Re-run with --global or from another project directory.

Recovery output

After a reset, human output reports each reset root with the number of removed custom or unrecorded files and modified stale files, each shared root that was not reset, and each pre-reset snapshot:

[i] Fresh reset: <reset-root> now holds only engineer output (removed 3 custom/unrecorded and 1 modified stale file(s))
[i] Pre-reset target saved (verified <id>). Roll back: <restore-command>

A snapshot outside restore scope reports Manual recovery data: <path> instead of a restore command. An accepted unverified snapshot is labeled UNVERIFIED, may be incomplete. If nothing existed to reset, the output says so and no snapshot is listed.

With --json, data.fresh carries resetRoots, notReset, snapshots (each with id, roots, verify_command, and either restore_command or manual_data_path, plus unverified when accepted), snapshotVerified, removedUnrecorded, removedStaleModified, and reason. The legacy top-level forceSnapshot field names only a verified snapshot, so it is empty when the only snapshot is an accepted unverified one. If the run fails after the snapshots, the error names each snapshot with its verify and restore route.

When ak kit init hands off to an updated CLI first, the continuation carries --fresh and any accepted --accept-risks token, never --force. Desktop, ak update, and ak doctor have no fresh mode.

How --fresh differs from --force

The two flags are mutually exclusive.

Read human and JSON output

In human modes, progress, the destination preview, and confirmation appear on stderr. The final result summary appears on stdout and reports the kit, output path, file count, install mode, scope, Hook summary, warnings, and any recovery information that applies.

With --json, stdout contains one versioned success envelope with kind=kit.init and command results under data. Unless --quiet is set, stderr also receives raw status records with status=preview before the write and status=complete after it. Consume stdout and stderr separately.

Success data can include the selected kit and targets, mode, install mode, scope, output directory, file and skill counts, installed Hook summary, warnings, project configuration state, mode transitions, and bounded recovery snapshot fields. Hook projection data can also include optional hooksDropped, droppedHookSummaries, hookMatchersNarrowed, and narrowedHookSummaries; zero or nil values are omitted.

Human and JSON execution errors show the recovery reason by default, including argument errors from the command's argument validation. Known secret shapes and URL query strings are redacted while paths remain visible. --verbose can expose the raw underlying error; review it before sharing.

Exit behavior

Exit meanings are command-local. In particular, do not interpret the TTY decline as the shared exit 3 promise.

Recover from a failed or forced install

When output includes a recovery snapshot, inspect it before changing more files:

ak backups show <id>
ak backups verify <id>

Some snapshots under AgentKit-owned restore roots can be applied with ak backups restore <id>. A project-local forced install can instead report a manual snapshot data directory because that output is outside normal restore scope. Follow the recovery method in the result; do not assume every snapshot is restorable by the same command.

After recovery or installation, reopen the target runtime and invoke one installed skill. If discovery fails, check target, project versus user scope, and Claude native versus plugin mode before reinstalling.

Read hook projection results

The success summary reports installed Hook events and scripts when present. Hook projection disclosures use separate lines:

Hook groups not projected: <count> group(s) - see warnings
Hook matchers narrowed (some tool matches unsupported on this target): <count> matcher(s) - see warnings

It then prints an actionable summary for each drop or narrow. A full drop removes the group; a narrow keeps handlers on supported matcher atoms.

For Codex, Engineer has one fully dropped task-state PostToolUse group and two shared narrowed matchers. Marketing has no full drop and three narrows. The install still succeeds: these are target limitations, not repaired Hooks or fatal installation errors.

Related commands

• Complete ak kit init command facts
• Install kits safely
• Kit installation troubleshooting
• Register an existing project with ak init
• Create a project with ak new
• Refresh an installed route

Hook groups not projected can be unsupported or deferred by the harness bridge. Read hooksDeferred separately from unsupported groups; deferred does not mean permanently unsupported.