Agents & models

Choosing which coding agent and model does the work, per step, per workflow, or per project.

Peractor coordinates coding agents; it is not one. Two are built in — Claude Code (claude, the default) and Codex (codex) — and your organization can register others. Every prompt-driven step can choose its provider, model, and reasoning effort.

Choosing, at three levels

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

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

Closest wins: the step's agent, else the workflow's default, else the project default in settings, else Claude at opus-5 and medium effort.

Mixing within one workflow is normal — a frontier model for the implementation, a fast one for the summary.

The catalog

These are what the pickers offer. A newer model id typed into the YAML is passed through to the agent as-is, so you are never blocked waiting for a catalog update.

Bringing your own agent

An admin can register a third agent under Settings → Agents: a label, an icon, the command that launches it, how the prompt reaches it, and the credential it authenticates with.

From then on it appears everywhere the built-in two appear — selectable on a workflow step, selectable as a project default, and it runs. Phones and the Mac pick it up without a new app build.

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 server they can also come from the host environment; the credential saved in the app wins when both exist.

What it costs

Claude reports exact dollars per phase. Codex reports none, so Peractor estimates from a rate table — a total that includes an estimate renders as ~$1.23.

Token counts are normalized to the same four buckets for both — input, output, cache read, cache write — so comparing agents is honest.