Pin versions

agents.yaml at the repo root pins each CLI's version. Every agents call inside the tree honors it.

The file

# agents.yaml
agents:
  claude: "2.1.207"
  codex:  "0.144.1"

agents run claude ... inside that tree resolves to Claude Code 2.1.207. Outside it, the call uses your global default. Same idea as .nvmrc or .tool-versions — the version travels with the repo, so every teammate runs the one the code was tested against.

Set a pin

Write agents.yaml by hand, or let the CLI do it. -p writes the pin to the project's agents.yaml; without it, agents use switches your global default.

agents use claude@2.1.207 -p    # pin this project to Claude Code 2.1.207
agents use codex@0.144.1 -p     # pin Codex for the whole team

Resolution order

A version is resolved by walking the config layers from most specific to least. The first layer that names the agent wins:

1. project — ./.agents/agents.yaml at the repo root.
2. you — ~/.agents/agents.yaml, your global default.
3. system — ~/.agents/.system/, the shared baseline.

So a project pin overrides your personal default, which overrides the system baseline. See config layers for how the same precedence governs skills, hooks, and rules.

Gate drift in CI

agents check exits non-zero when any installed version is out of sync — stale, or never synced against what agents.yaml pins. Wire it into a CI step so a drifted machine fails the build instead of silently running the wrong version.

agents check              # exit 1 if anything drifted, 0 when clean
agents check --quiet      # just the verdict line
agents check --json       # machine-readable, for scripting

# Gate in a CI step
agents check || { echo "resources drifted — run 'agents doctor --fix'"; exit 1; }

When it fails, agents doctor --fix heals the gaps by installing the pinned versions and re-syncing resources.

Related: Run, Rotate accounts, Config layers.