How do I set `maxEffortLevel` in Claude Code?

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.

Prerequisites

• Claude Code ≥ 2.1.267 - CHANGELOG introduced the key there; settings-reference still documents it. CHANGELOG head at check time: 2.1.284 (Claude Sonnet 5.5; prior Claude Opus 5.5; catch-up 2.1.273-278).
• CHANGELOG 2.1.280 note (still applies): An effort level saved before /effort became per-model may not apply to newly released models such as Opus 5.5 or Sonnet 5.5; pick a level if needed. Pro and Team Standard defaulted to Opus at 2.1.280; 2.1.284 makes Sonnet 5.5 the default Sonnet — see Claude Sonnet 5.5.
• Check your version with claude --version before relying on the key. We haven't re-tested it in the CLI; this page follows the docs and CHANGELOG.
• 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".

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 from the settings reference (the model ID is Anthropic's own example):

{
  "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

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. CHANGELOG 2.1.284 also turns Ultracode into its own /effort toggle (no longer forces xhigh) — confirm locally if you rely on the older coupling.
• 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.
• Using values the docs don't list. Only low, medium, high, xhigh and max are documented.

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-29)

• 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; 2.1.280 effort carry-over reset for newly released models; head 2.1.284 (default Sonnet 5.5; Ultracode toggle)
• Claude Sonnet 5.5 - default Sonnet on 2.1.284