Onboarding

Configure AgentKit, authenticate safely, install Engineer Kit, and verify your first runtime.

Onboarding is complete when your chosen coding assistant recognizes an Engineer Kit skill in a project you control.

Before you start

You need:

ak on your PATH — see Installation.
Claude Code or Codex installed and signed in with that runtime's own account.
An AgentKit account with access to Engineer Kit.
A test project where you are comfortable adding runtime configuration.

AgentKit authentication grants access to licensed kits. It does not sign Claude Code or Codex in to their providers, and runtime login does not grant AgentKit kit entitlement.

Configure AgentKit

ak setup

The wizard detects Claude Code and Codex login state, lets you choose enabled runtime adapters, and atomically updates ~/.agentkit/config.yaml with the default kit and telemetry preference. Re-running it is idempotent. Basic setup does not copy runtime credentials and does not install a kit.

Use these commands for different jobs:

Command	Use it for	Main result
`ak setup`	Configure this user's AgentKit preferences	Updates AgentKit configuration; no kit content
`ak init [dir]`	Adopt an existing directory	Creates or updates its AgentKit ownership manifest
`ak new <project-name>`	Start a new project directory	Creates the directory and its ownership manifest
`ak kit init <kit>`	Add a kit to a runtime	Writes runtime-ready kit content at project or user scope

You do not need ak init before installing a project-scoped kit; use it when you want AgentKit to adopt and track an existing project as a whole.

If the project already uses docs/ or plans/ for another purpose, choose project-relative AgentKit locations while adopting it:

ak init ./myproj --docs-dir handbook --plans-dir work/plans

The command persists the values as paths.docs and paths.plans in .agentkit/config.yaml. Relative values must remain inside the project and cannot point into .agentkit; an invalid value exits before initialization writes project state. A relative paths.plans value is used by Engineer Skills, ak plan, journals, and the Desktop/dashboard plan views.

Use the same AgentKit account that owns the kit. A successful login with a different account can still return no Engineer Kit grant.

User API key (recommended)

Create a user API key in the Account Dashboard, then run this locally with your real key:

ak login --api-key ak_live_... --no-interactive

This method suits regular use and non-interactive environments. AgentKit stores the API key and CLI session in restricted files under ~/.agentkit/auth (or %USERPROFILE%\.agentkit\auth on Windows) so the session can renew.

Email OTP

ak login --email you@example.com

AgentKit sends a one-time code to that address and prompts for it. The OTP is not persisted; the resulting renewable session is stored locally. If the message does not arrive, check Spam, Junk, and Promotions, then confirm the address is the account that owns the kit.

License key device activation

ak login --license-key ak_license_... --no-interactive

This activates the current device and stores an App device session separately from the CLI session created by API-key or email login. Add --device-name <name> only when you need an explicit device label. Kit grants are still checked separately.

Never put a real API key, license key, OTP, session file, or provider credential in source control, documentation, screenshots, diagnostics, or a support message. Avoid leaving literal secrets in shared shell history; rotate any credential that may have been exposed.

Verify identity and entitlement

ak whoami
ak licenses

ak whoami confirms the current account and live authentication state. ak licenses lists its per-kit grants. Continue only when Engineer Kit appears. Sign-in and entitlement are separate checks: logging in successfully does not create a missing grant. With no local session, ak whoami reports an unauthenticated state and exits 0; scripts must inspect the result instead of treating a zero exit code as proof of login.

Install Engineer Kit

Change to your test project, choose the runtime, and review the installation preview before confirming.

ak kit init engineer --target claude-code

ak kit init engineer --target codex

These are project-native installs from the authenticated remote registry and the stable kit channel by default. For Claude Code, plugin delivery requires --switch-to-plugin; independently, --global selects the runtime's user scope instead of project scope. A successful summary names engineer, the output location, install mode, scope, and number of files written.

On Codex, success can disclose both fully dropped Hook groups and partially narrowed matchers. Engineer currently projects one full drop—the unsupported PostToolUse task-state group—and two shared matcher narrows that keep their supported tool atoms active. Human output uses Hooks dropped (unsupported on this target) and Hook matchers narrowed (some tool matches unsupported on this target); neither disclosure means the install failed.

On Windows, eligible .cjs Hooks inside the resolved Codex home can use managed sibling .cmd shims when paths contain spaces. Engineer's plan reminder is registered on Stop: it stays silent when no active plan is bound and otherwise returns valid, nonblocking JSON. The reminder is not shipped as a SubagentStop registration.

Run and verify the first skill

Restart the assistant or open a new session so it reloads the installed content, then invoke:

/ak:cook Add a health-check endpoint

Use the /ak:... slash-command form in Claude Code.

$ak:cook Add a health-check endpoint

Use the $ak:... dollar-prefixed skill form in Codex.

Onboarding is complete when the assistant recognizes ak:cook, reads the request, and begins the skill workflow in the current project.

Recovery and common failures

ak whoami is unauthenticated: run one explicit ak login method again.
Engineer Kit is absent from ak licenses: confirm you used the purchasing account. Reinstalling cannot create entitlement.
Runtime missing or logged out: install it and use claude auth login or codex login, then re-run ak setup.
The skill is not recognized: confirm the install summary named the intended target, restart the assistant, and run ak doctor --exit-on-fail before reinstalling.
The destination conflicts with existing content: stop and review the ownership warning. Do not add --force as a first response.

AgentKit preserves unknown and user-modified files during normal kit operations. When a supported destructive change needs a recovery snapshot, the CLI prints a backup ID. Keep it until you have verified the result. Inspect, verify, and preview the snapshot before applying it:

ak backups show <backup-id>
ak backups verify <backup-id>
ak recover <backup-id> --dry-run
ak recover <backup-id>

Restore is replace-only: it restores captured paths but normally preserves unrelated files created later. A multi-file restore is not transactional and can stop after some writes if the host fails. For a project bundle, repeat the exact --allow-root values shown by ak backups show when the restore requests them.

Continue with the focused Quickstart, or read Installing kits before changing scope, selecting skills, or refreshing an installation.

On this page