Choosing subagent models

Each Kit Agent names a runtime-neutral capability tier (opus, haiku, fable, sonnet, or inherit), and each runtime adapter maps that tier to a model it understands. ak agents model lets you replace that choice for one Agent, and agent_models config lets you remap a whole tier.

Your choice lives in AgentKit config, not only in the generated Agent file. Every install, ak update, and ak kit refresh resolves the model from config again, so an override survives updates, refreshes, and reinstalls instead of being overwritten by the Kit default.

For the default mapping of each Kit Agent on each runtime, see Agent models across runtimes.

Commands at a glance

Every subcommand takes --runtime (claude-code, codex, cursor, omp, or pi) and --project <dir> to select a project other than the current directory. list and apply read every runtime when --runtime is omitted. --json emits machine-readable output. Run ak agents model <command> --help for the full flags and exit codes.

Examples

# See every installed Agent and its status.
ak agents model list

# Put kongming on Opus in Claude Code.
ak agents model set kongming --runtime claude-code --model opus

# Codex model and reasoning effort, for this project only.
ak agents model set kongming --runtime codex --model gpt-5.5 --effort high --scope project

# OMP: point an Agent at an OMP role alias.
ak agents model set planner --runtime omp --model @plan

# Pi: pin a provider/model ID.
ak agents model set debugger --runtime pi --model anthropic/claude-sonnet-4-5

# Let a Cursor Agent run on the parent session's model.
ak agents model inherit code-reviewer --runtime cursor

# Drop the project override and fall back to the next layer.
ak agents model reset kongming --runtime codex --scope project

# Ask which layer decides, and why.
ak agents model explain kongming --runtime claude-code

set also accepts --model inherit. ak agents model changes one Agent at a time; to remap a whole tier, use config keys.

set, inherit, reset, and adopt back up the config file they change before writing, then update every installed file of the Agent whose model AgentKit still owns. A file whose model was edited in the runtime is left alone and reported; see Status and drift.

Setting a model for an Agent that is not installed yet still writes config, with a warning; the value applies when a Kit installs that Agent.

Scopes

--scope selects which config file a command writes:

• user (default) writes your AgentKit home config, normally ~/.agentkit/config.yaml.
• project writes .agentkit/config.yaml in the project.

A project install reads both files. A global install reads user config only; project config never reaches a shared global install. If an Agent is installed globally, a --scope project override does not change it.

Precedence

From highest to lowest:

1. Project per-Agent override
2. User per-Agent override
3. Project tier override
4. User tier override
5. Kit frontmatter and adapter default

The two config files are merged field by field, so a project can set only reasoning_effort for an Agent and keep the user's model for it. On OMP, when the result is an @role alias, a project role binding and then a user role binding can replace it with a concrete model; see OMP role aliases. ak agents model explain <agent> shows which layer decides each installed file.

Status and drift

list reports one status per installed Agent file:

AgentKit records which model it chose for each file. When you edit a model directly in a runtime Agent file, a later refresh keeps your edited model, still updates the rest of the file (instructions, description), warns, and reports the file as drift. Settle drift in one of two ways:

• Keep the runtime edit: ak agents model adopt <agent> --runtime <runtime> records the model the file carries now in config, so refreshes stop reporting it. Choose the scope the install actually reads: a global install reads only user config, and a project config that pins the Agent outranks a user-scope adopt. If the chosen scope reaches none of the files, adopt refuses and leaves config unchanged.
• Replace the runtime edit: ak agents model apply writes the configured model. Pending files are updated directly; drifted files are replaced only with confirmation, and each is backed up first. In a terminal, apply asks. In scripts and CI, pass --yes; without confirmation nothing is written and --json output names the files under need_confirmation.

adopt and apply first check that AgentKit still owns each file: the file is reached without a link and matches AgentKit's ownership record apart from its model. If a file fails that check, they refuse before changing anything.

ak agents model adopt kongming --runtime codex
ak agents model apply kongming --runtime codex --yes

Codex rewrites its role files on every refresh: only the kept model fields survive, and other edits to a Codex role file are replaced. Before AgentKit has recorded its choice for a Codex role file, for example on the first refresh after upgrading, an edited file carries no ownership proof, so its model is replaced with a warning naming the value it replaced.

On Claude Code, Cursor, and OMP, a file edited beyond its model is left alone. Pi replaces such a file on refresh; an install refuses it unless you pass --force.

Effective model certainty

get and explain report the effective model with a certainty:

• derived: the runtime file names the model the runtime runs.
• unknown: the runtime decides. This applies when the Agent inherits the parent session's model, when no readable file exists, when the runtime can override the file through a setting AgentKit does not read (OMP and Pi), and for a directly edited Claude Code plugin Agent until ak kit refresh re-activates the plugin, because Claude Code runs plugin Agents from its own plugin cache.

When the certainty is unknown, confirm the model the running Agent reports.

Manage models from the Desktop

The AgentKit Desktop app and the web dashboard that ak config start serves show the same data on Subagents -> Models. For each managed Agent file you see its kit default, desired value and source layer, effective model with certainty, and status. Each runtime shows its support status. A capability-gated runtime has no edit controls. The page calls the same service as ak agents model, so ownership checks, the lifecycle lock, and backups apply unchanged.

• Pick the write scope: User, or Project while a project is open. This matches --scope user|project.
• Set, Inherit session model, Reset, and Adopt (shown for drift) match set, inherit, reset, and adopt.
• Reapply matches apply. When files were edited outside AgentKit, the page lists them and asks before replacing them. Each replaced file is backed up first.
• Explain shows the precedence layers and which one decided, like explain.

Runtime support

Runtimes not listed, such as Antigravity (agy), are not rated yet.

A capability-gated runtime is never a silent no-op: ak agents model and ak config prefs set reject it (run with --verbose or --json to see the reason), and an install or refresh warns once about any agent_models keys you authored for it by hand. Remove them all at once, adding --scope project for project config:

ak config prefs unset agent_models.grok

Only a capability-gated runtime's section can be removed whole; on other runtimes, unset one key at a time.

Codex, Cursor, OMP, and Pi reject the bare tier names (opus, sonnet, haiku, fable) as model IDs. Values are checked for shape only, never against a model catalog, so a well-formed ID your account cannot use is reported by the runtime, not by AgentKit.

OMP role aliases

On OMP, a model value can be a provider/model ID or an @<role> alias from OMP's role set: @advisor, @commit, @default, @designer, @plan, @slow, @smol, @task, @tiny, @vision. By default AgentKit maps the Kit tiers to roles: sonnet to @task, opus to @plan, haiku to @smol, and fable to @advisor.

Without a binding, AgentKit writes the alias and OMP resolves it through its own modelRoles. To have AgentKit write a concrete model instead, bind the role in AgentKit config:

# Route the sonnet tier through @smol, then bind @smol to a model.
ak config prefs set agent_models.omp.sonnet @smol
ak config prefs set agent_models.omp.roles.smol.model anthropic/claude-haiku-4-5
ak config prefs set agent_models.omp.roles.smol.reasoning_effort low

An Agent whose resolved value is a bound alias gets the bound model, and its reasoning effort is written as thinking-level. A per-Agent effort outranks the role's. A role binding must be a model, not another alias. To configure OMP's own modelRoles instead, see Configure OMP roles.

Config keys

ak agents model writes these keys for you. You can also set them directly with ak config prefs set:

The existing Cursor tier key keeps working:

ak config prefs set agent_models.cursor.opus YOUR_CURSOR_MODEL_ID

A key set this way lands on the next ak update or ak kit refresh; run ak agents model apply to write it into installed files now. A per-Agent key that matches no installed Agent produces an install warning naming the key.