Runtime adapters

Coding assistants do not share one file layout, tool set, or lifecycle event model. A runtime adapter converts a Kit into the surfaces the selected assistant can actually discover and use.

An adapter is a compatibility boundary, not a promise of identical behavior. If a runtime has no equivalent for a component, AgentKit may preserve it as inactive supporting content, drop it with a warning, or report it as unsupported.

Project and user scope

Scope answers where the installation is available:

Scope does not determine ownership of your repository. A project-scoped install lets AgentKit manage its recorded installation files in that project; it does not make every project file AgentKit-owned.

Project and user copies can coexist. The runtime may then shadow or duplicate a command or Hook, and updating or removing one scope does not automatically delete the other. Inspect both scopes when behavior appears twice or a runtime loads a different copy than expected.

Native and plugin delivery

Delivery answers how the runtime loads the installation:

• Native delivery writes supported components to the runtime's normal project or user locations. It is the default install mode.
• Plugin delivery packages and activates the Kit through a runtime's plugin mechanism. In the current supported model, this is an explicit Claude Code choice made with --switch-to-plugin, at either project or user scope.

Scope and delivery are independent. Claude Code can therefore use project-native, user-native, project-plugin, or user-plugin delivery. Codex, Cursor, DeepSeek Harness, Grok, Pi, and Oh My Pi installs use their native project or user layouts. Local-source Grok and DeepSeek Harness installs remain available for development and CI with an explicit --local --kits-dir source. --switch-to-plugin does not select plugin delivery for these targets.

Within one scope, native and plugin delivery for the same Claude Code Kit are mutually exclusive. Selecting the other mode starts an explicit transition; it does not leave both AgentKit-owned copies active in that scope.

Switching delivery mode is a lifecycle transition. Review the preview because AgentKit may need to withdraw its old registration and create a new one while preserving foreign or modified content.

Capability differences

The supported adapters share core file and tool workflows, but their active surfaces differ:

Pi projection and discovery

A project install with ak kit init <kit> --target pi writes portable Skill directories such as .pi/skills/ak-cook/SKILL.md, remapped Agents such as .pi/agents/Explore.md, .pi/agents/Plan.md, and kit-scoped .pi/agents/ak-<kit>-*.md, plus owned rules under .pi/rules/. Hooks, coding-level files, the emitted kit statusline .cjs, runnable scripts, and sidecars live under .pi/extensions/agentkit-hooks-<kit>/; the shared Agent runner lives under .pi/extensions/agentkit-agent/. AgentKit does not write .pi/commands/ or register Pi slash commands. The kit statusline file is emitted beside the extension; Pi keeps its native TUI footer unless you pass an explicit non-none statuslineMode.

With --global, AgentKit writes directly below the active Pi coding-agent profile, resolved from PI_CODING_AGENT_DIR or ~/.pi/agent; it does not add an extra .pi/ segment under that profile. A fresh install refuses an occupied profile by default. Pass --force only after reviewing the occupied paths and deciding to authorize the overwrite. Pi projection is separate from Oh My Pi dispatch: this release does not provide ak run --target pi or wrap Pi's agent loop.

Oh My Pi projection and discovery

A project install with ak kit init <kit> --target omp writes portable Skills below .omp/skills/ak-<slug>/, with top-level name: ak-<slug> in each projected SKILL.md. Agents go to .omp/agents/<name>.md, and rules go to .omp/rules/<name>.md. Body aliases such as /ak:cook and $ak:cook are not rewritten. AgentKit also adds one Kit-scoped block to the project's AGENTS.md, delimited by <!-- AGENTKIT-OMP:START:<kit> --> and <!-- AGENTKIT-OMP:END:<kit> -->. Updating or uninstalling that Kit changes only its managed block and preserves user content.

With --global, AgentKit resolves the OMP root in this order: AGENTKIT_OMP_HOME, OMP_HOME, PI_CODING_AGENT_DIR, then ~/.omp/agent. The same skills/, agents/, and rules/ directories plus AGENTS.md live below that resolved root. Commands, Hooks, schemas, scripts, status-line files, and other unsupported Kit surfaces stay inactive under .agentkit/adapters/omp/<kit>/sidecars/ instead of being projected as native OMP behavior.

Installation and dispatch are separate routes. ak kit init ... --target omp creates the discoverable Kit projection; ak run <kit>/<skill> --target omp runs one resolved Skill through the local OMP CLI without replacing that installed inventory or changing the <kit>/<skill> selector.

Trusted project OMP also discovers project .agents/skills. If canonical forms such as ak:advise and ak-advise collide, a project OMP install in .omp/skills shadows the project .agents/skills copy. When you use a global OMP install from that trusted project, the project .agents/skills copy shadows the OMP profile copy. ak kit init --target omp warns and continues: it still emits OMP content, does not delete or rewrite either Skill, does not alter .agents or OMP settings, and does not require --force or return exit 6.

Native Grok exec-form command Hooks use the owned agentkit-grok-envelope-shim.cjs launcher to add the Claude-shaped fields and tool names that Kit scripts expect. HTTP handlers and command handlers without exec-form arguments receive Grok's raw camelCase envelope. Project Hooks remain inactive until you explicitly trust the project. Hook timeout, crash, malformed output, and shim errors fail open; only an applicable PreToolUse denial blocks the action, so pair safety-sensitive Hooks with Grok permissions.

ak run <kit>/<skill> --target dsh and ak run <kit>/<skill> --target grok are native AgentKit dispatch routes. DeepSeek Harness resolves AGENTKIT_DSH_BIN or dsh; Grok resolves AGENTKIT_GROK_BIN or grok. AgentKit owns process framing, while the runtime and user own the model, authentication, trust, permissions, sandbox, and native config. Grok dispatch is separate from Grok's Claude-compat scanner reading .claude settings. Remote DeepSeek Harness and Grok init and refresh use signed registry packages. Use --local --kits-dir only when you intentionally select a development or CI source.

For native Claude Code Hooks, AgentKit checks the complete runtime closure before changing files. Preflight stops without mutation when untracked or modified content would collide with runtime-owned output. Replacement requires an explicitly authorized force operation, and a collision introduced after preflight is still rejected by the final check instead of being overwritten.

A Codex projection limit does not fail the installation. A fully unsupported group is omitted and listed under Hook groups not projected; JSON can include hooksDropped and droppedHookSummaries. A partial matcher keeps its handlers on the supported atoms and is listed under Hook matchers narrowed (some tool matches unsupported on this target); JSON can include hookMatchersNarrowed and narrowedHookSummaries. All four fields are optional and omitted at zero.

For Engineer, the unsupported task-state PostToolUse group is fully dropped, while two shared matchers are narrowed. For Marketing, three matchers are narrowed and no group is fully dropped. These are capability disclosures, not new failure classes. Claude Code and Cursor adapter destinations and inventories are unchanged; do not infer new Cursor parity from shared package changes.

On Windows, AgentKit can make an eligible .cjs Hook inside the resolved Codex home work from an ordinary path containing spaces by creating a managed sibling .cmd shim. This does not cover a spaced external path, a path with cmd.exe metacharacters, a non-ASCII shim name, or unsafe/non-ASCII baked arguments; those cases remain unsupported on Windows and warn. Empty arguments are rejected distinctly, identical same-path shims deduplicate, and a conflicting same-path shim keeps the first emitted content and warns. Paths that do not need a shim continue to use the direct command.

A wrapper-managed Codex home may link only its final hooks leaf to the resolved user's canonical ~/.codex/hooks directory. The link may be a POSIX symlink or a Windows directory junction. AgentKit resolves that alias once and uses the canonical path for Hook writes, commands, rollback, and ownership. A linked parent, or a leaf that resolves to anything other than the canonical user hooks directory, is refused.

Do not infer runtime support from a file name or from another runtime's behavior. Use the install summary and the relevant Skill documentation as the authority for what became active. A warning about preserved or omitted content is a capability result, not necessarily a failed installation.

Choosing an adapter

1. Choose the assistant where you will run the workflow.
2. Choose project or user scope based on where it should be available.
3. For Claude Code, keep native delivery unless you deliberately want plugin activation and lifecycle.
4. Choose DeepSeek Harness with --target dsh when you want the signed DeepSeek Harness Kit package, or use ak run --target dsh for direct Skill dispatch through the local dsh binary; add --local --kits-dir only for development or CI sources.
5. Choose Grok Build with --target grok when you want the signed Grok Kit package; add --local --kits-dir only for development or CI sources.
6. Choose Oh My Pi with --target omp when you want the signed OMP Kit package, or use ak run --target omp for direct Skill dispatch.
7. Review adapter warnings after installation, especially for Hooks and runtime-only UI surfaces.
8. Start a fresh runtime session if the assistant has not reloaded newly installed content.

For installation commands, see Installing kits. For the component model, see Kits, Skills, Agents, and Hooks.

Runtime capability matrix

Package availability is release-bound; installation does not prove dispatch or live provider parity.

AGY is not a full refresh peer. Its global export and ownership cleanup do not imply ak run --target agy support. Setup target choices exclude export-only targets. cloud-harness is likewise not a kit init, setup, or ak run target; the Cloud Harness MCP harness consumes its signed package directly. No fresh live provider canary is claimed by this matrix.

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.

For model selection and Agent-specific overrides, read Agent models across runtimes.