Agents & models

Claude and Codex, the model catalog, reasoning effort, and where credentials live.

Peractor coordinates coding agents; it isn't one. Two providers are built in — Claude Code (claude, the default) and Codex (codex) — and every prompt-driven step can choose its provider, model, and reasoning effort.

Choosing, at three levels

# workflow-wide
defaults:
  agent: { provider: claude, model: opus-4.8, effort: high }

# per step
- type: prompt
  prompt: Summarize what changed and any follow-ups.
  agent: { provider: claude, model: haiku-4.5 }

Resolution is closest-wins: the step's agent, else the workflow's defaults.agent, else the project default in settings, else Claude at opus-4.8 / medium. Mixing within one workflow is normal — a frontier model for the implementation, a fast one for the summary.

The catalog

Provider	Model	Effort levels
`claude`	`opus-4.8` (default)	low · medium · high · xhigh · max
	`sonnet-4.6`	low · medium · high · max
	`haiku-4.5`	—
`codex`	(unset — the CLI's default)	low · medium · high
	`gpt-5.6-sol` · `gpt-5.6-terra` · `gpt-5.6-luna`	low … max
	`gpt-5.5` · `gpt-5.4` · `gpt-5.1-codex-max`	low … xhigh
	`gpt-5.3-codex` · `gpt-5.1-codex`	low · medium · high

These are what the pickers offer; a newer model id typed into the YAML is passed through to the agent CLI as-is, so you're never blocked on a catalog update.

Credentials

Credentials never appear in workflow YAML. Connect them once in Settings → Model providers — a Claude subscription token or Anthropic API key, an OpenAI API key for Codex. On a self-hosted deployment they can also come from the host environment (CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY); the in-app credential wins when both exist.

Cost display. Claude reports exact dollars per phase. Codex reports none, so Peractor estimates from a rate table — totals that include an estimate render as ~$1.23. Token counts are normalized to the same four buckets for both (input, output, cache read, cache write), so cross-agent comparisons are honest.