How do I set `maxEffortLevel` in Claude Code?

Set maxEffortLevel in Claude Code settings (2.1.267+) to cap effort across every provider. Lowest scope wins. It is not the same as effortLevel.

On Claude Code 2.1.267+, add "maxEffortLevel": "medium" (or low / high / xhigh / max) to a settings file. Higher effort requests clamp to the cap; you can still pick a lower level. Put it in user, project, local, or managed settings - when several scopes set a cap, the lowest wins. Prefer this key over effortLevel when you need enforcement, not a default.

TL;DR. Cap with maxEffortLevel in settings.json (2.1.267+). Values: low · medium · high · xhigh · max ("max" = no cap from that source; unset = no cap). Client-side before each request → every provider. Per-model under modelSettings. Lowest cap across scopes wins.

Prerequisites

Claude Code ≥ 2.1.267 - CHANGELOG introduced the key there; settings-reference still documents it. CHANGELOG head at write time: 2.1.278 (catch-up fiche).
[GAP]: claude --version not available in this write environment - confirm locally before relying on the key.
Know the scope: ~/.claude/settings.json (user), .claude/settings.json (shared project), .claude/settings.local.json (local), managed / --settings.

Set a global cap

Paste a top-level string into the settings file the session loads:

{
  "maxEffortLevel": "medium"
}

Allowed values from the settings reference only: "low" | "medium" | "high" | "xhigh" | "max".

Value	Effect
`low` … `xhigh`	Hard ceiling at that level
`"max"`	No cap from that settings source
unset	No cap

The cap applies to /effort, the /model picker, --effort, CLAUDE_CODE_EFFORT_LEVEL, skill/subagent effort frontmatter, and the model’s own default. Claude Code applies it client-side before each request, so it holds on Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, and first-party.

Per-model caps under `modelSettings`

Official example (settings-reference - do not invent other model IDs here):

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

A per-model maxEffortLevel replaces the top-level key for that model within the same settings source. "max" there exempts the model from that source’s top-level only; caps from other scopes still apply.

`maxEffortLevel` vs `effortLevel`

Control	Role
`maxEffortLevel` / `modelSettings.*.maxEffortLevel`	Hard ceiling (enforcement)
`effortLevel` / `modelSettings.*.effortLevel`	Default / saved preferred level - user can still go higher unless capped
`/effort`, `--effort`, `CLAUDE_CODE_EFFORT_LEVEL`	Session/request level - clamped by the cap
Skill/subagent frontmatter `effort`	Override while active - still limited by the cap

Use effortLevel when you want a preferred starting point. Use maxEffortLevel when cost or latency policy must not be raised by /effort or frontmatter. Related ops after settings edits: how to use /skill-doctor.

Lowest-cap-wins + providers

Unlike “managed always overrides” intuition, maxEffortLevel is a documented exception: when several scopes set a cap (including --settings), the lowest applies - a higher managed or user value cannot raise a lower project/local/user/managed/--settings cap. See settings precedence.

If the organization also sets an effort limit for a model (model config), the lower of the two applies.

Pitfalls

Cap below xhigh → ultracode unavailable on affected models. Ultracode needs xhigh (or no cap below it); with a lower cap the session runs at the cap and ultracode stays off.
Expecting managed high to override project low - it won’t; lowest-cap-wins.
Confusing "max" with “force max effort” - "max" means no ceiling from that source, not “always run at max.”
Wrong version - below 2.1.267 the key is ignored / unknown.
Don’t invent enum values or model IDs beyond the docs example.

Settings adjacency (attribution keys, not effort): turn off commit attribution. Git permission noise is a separate upgrade path: read-only git prompts.

FAQ

Can users still pick lower effort?
Yes. The cap only blocks levels above it.

Does "max" force max effort?
No. It means no ceiling from that settings source.

Where should orgs put it?
Managed settings, so the floor is organization-wide. Remember lowest-cap-wins if a project also sets a lower value.

Does skill/subagent frontmatter effort bypass the cap?
No. Frontmatter is still limited by maxEffortLevel.

How do I set a default effort without enforcing a ceiling?
Use effortLevel / /effort / per-model modelSettings.*.effortLevel - see model configuration. This page is the cap only.

Sources (checked 2026-09-20)

Settings reference - maxEffortLevel - values, scopes, lowest-cap-wins, per-model, ultracode, providers, official JSON example
Settings files and precedence - maxEffortLevel lowest-cap exception (incl. --settings)
Model configuration - org effort limits vs client maxEffortLevel; effortLevel as default not enforcement
CHANGELOG.md - 2.1.267 added maxEffortLevel; head 2.1.278 (still present)
[GAP] CLI --version unavailable in write environment