ak agents model
ak agents model set
Pin an Agent's model or reasoning effort in user or project config and apply it to the Agent's owned installed files.
Use ak agents model set to choose the model one Agent runs on. The value is
stored in AgentKit config, so installs, updates, and refreshes keep it.
Usage
ak agents model set <agent> --runtime <runtime> [--model <id>] [--effort <level>] [--scope user|project] [--project <dir>]Exactly one Agent name is required, plus at least one of --model and
--effort. Passing neither exits 2 with nothing written.
| Flag | Default | Description |
|---|---|---|
--runtime <runtime> | required | One of claude-code, codex, cursor, omp, pi. |
--model <id> | none | Runtime model ID, inherit to use the parent session's model, or an @role alias on omp. |
--effort <level> | none | Reasoning effort for codex and omp only: one lowercase word such as low, medium, or high. |
--scope user|project | user | Config to write: the AgentKit home, or .agentkit/config.yaml in the project. |
--project <dir> | nearest project config, else the current directory | Project whose installs and config apply. |
What it writes
The command writes agent_models.<runtime>.agents.<agent>.model and, with
--effort, reasoning_effort to the selected scope. A project value outranks
a user value for project installs; global installs read user config only.
Model IDs are checked by shape, not against a catalog. They must be a single
printable token that does not start with a YAML or flag character. Cursor IDs
cannot be provider-qualified. Tier names such as opus are rejected for
codex, cursor, omp, and pi. OMP @role aliases must be a documented
role. --effort on claude-code, cursor, or pi exits 2 because those
runtimes carry effort in the model ID.
Side effects
- Takes the kit lifecycle lock.
- Backs up, then rewrites, the scope's
config.yamlwhen it exists. Project scope scaffolds.agentkit/config.yamlfirst when needed. If a later edit fails, the config is restored so the edits land together or not at all. - Rewrites the model fields of every installed file of the Agent whose model AgentKit still owns.
- A file edited in the runtime (
drift) or whose ownership AgentKit cannot prove is left alone and named in a warning. Useapply --yesoradopt. - Claude Code plugin files take effect after
ak kit refreshre-activates the plugin; a warning says so. - With no installed file of the Agent, config is still written and a warning says the value applies when a kit installs it. This is not an error.
Output
Human stdout reports set <runtime> agent <agent> in <config path> (or that
the config had nothing to change), one updated <path> line per rewritten
file, then the status table.
JSON success uses:
schema_version: 1
kind: agents.model.set
data.action, data.runtime, data.agent, data.scope
data.config_path, data.config_changed
data.backup_paths?, data.applied?
data.agents[], data.warnings?Exit behavior
| Exit | Meaning |
|---|---|
0 | Config was written or already matched. |
1 | Command failure, such as a config write error. |
2 | Neither --model nor --effort, an invalid Agent name, model, effort, or scope, an unsupported runtime or field, project scope with no project directory, or a missing --project directory. |
4 | Another AgentKit operation holds the kit lifecycle lock. |