Skip to content
teamctl

Per-agent reasoning effort

Some agents on a team carry more weight than others. The release_manager deciding what ships, the playtest_critic looking for the design flaw nobody else will admit — those want every cycle the runtime can spare. The triage worker scanning a hundred new issues a day does not. The effort: field on a per-agent compose entry lets you tune that knob per role.

YAML

.team/projects/oss.yaml
managers:
  release_manager:
    runtime: claude-code
    model: claude-opus-4-8
    role_prompt: roles/release_manager.md
    permission_mode: plan
    effort: max          # ← per-agent reasoning effort

Five values, lowest to highest:

ValueNotes
lowQuickest. Good for triage, log-watching, mechanical agents.
mediumDefault-ish. Most workers.
highDeeper analysis. Architecture-leaning roles.
xhighOne step short of max.
maxStrongest reasoning. Reserve for plan-mode dissenters and release-critical roles.

teamctl validate rejects unknown values at parse time — effort: hgih fails immediately with the valid set enumerated, rather than silently falling back to a wrapper default.

Precedence

When more than one source sets an effort, the highest-priority one wins:

  1. Per-agent YAML — effort: in the agent’s compose entry.
  2. Workspace .env — EFFORT= exported into the team’s environment.
  3. Unset — the runtime’s own default.

In practice that means: a workspace-wide floor in .env is overridden by any agent that explicitly sets its own value. Agents that don’t set effort: inherit the workspace setting; agents that don’t, and aren’t under a workspace setting, run on the runtime’s default.

When to set it

Reach for effort: when:

  • One agent on the team carries the deciding output and the rest feed into it (release planners, lead editors, plan-mode critics).
  • A team mixes deep thinking with bulk throughput, and one effort setting for everyone would either over-spend on routine work or under-spend on the critical role.

Skip it when the team is uniform — a workspace .env setting reads cleaner than five identical YAML lines.

See also