Add maxEffortLevel to your Claude Code settings — either top-level or per model under modelSettings — and every session is capped at that reasoning-effort ceiling on every provider, including Bedrock, Vertex and Foundry, whilst users can still choose a lower level whenever they want. That is the new Claude Code max effort level control, shipped in version 2.1.267 on 9 September 2026 per the official Claude Code changelog, and refined further in 2.1.268 on 10 September 2026.
📺 Watch: Claude Code Just Got a HUGE Customization Upgrade
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside · Want AI SEO help 1-on-1? Book a free SEO strategy session →
Effort levels decide how much reasoning a model spends on each request — and therefore how much it costs and how long it takes. Until this release, effort in Claude Code was largely a per-user, per-session affair: whoever ran the session picked the level, and teams had no way to enforce a ceiling. maxEffortLevel changes that, and the 2.1.268 follow-up fixed the rough edges around how effort behaves across models and mid-session changes. Everything below is drawn directly from the official changelog, with version numbers and dates named so you can check each claim.
Here is what shipped, what each piece does, and how to decide where your ceiling should sit.
What The Claude Code Max Effort Level Setting Does
Per the 2.1.267 changelog entry (9 September 2026), the setting "caps the effort level on every provider" — and the provider list is the notable part. Teams running Claude Code through Amazon Bedrock, Google Vertex or Azure Foundry get the same cap behaviour as direct API users, which makes maxEffortLevel one of the few effort controls that works uniformly across enterprise deployments.
Two design decisions stand out in the official wording:
- It is a ceiling, not a pin. Users "can still pick a lower level" — the setting stops sessions from going above the cap, it never forces expensive reasoning on requests that do not need it.
- It can be global or per model. You set it top-level for a blanket policy, or per model under modelSettings when different models deserve different ceilings — a sensible split, since the cost gap between effort levels varies a lot by model.
The obvious use case is spend control. Reasoning effort is a direct multiplier on token consumption, and an organisation that has watched a few runaway high-effort sessions burn through budget now has a one-line policy answer. If that is the problem you are solving, pair the cap with the tactics in how to reduce Claude Code token usage — the cap sets the ceiling, those habits lower the floor.
If you want to run Claude Code like an operation rather than a hobby — configs, workflows and cost controls included — the AI Profit Boardroom has daily tutorials, prompt libraries and weekly live coaching calls: join the builders inside. Prefer 1-on-1 help first? Book a free SEO strategy session and get a plan for your own stack.
The Other Effort Changes That Landed With It
Version 2.1.268 (10 September 2026) shipped three effort-related changes alongside the cap, and together they make effort behave the way you would expect it to:
| Change | Version | What it means in practice |
|---|---|---|
| maxEffortLevel setting added | 2.1.267 (9 Sept 2026) | Cap effort globally or per model, on every provider |
| /effort saves a default per model | 2.1.268 (10 Sept 2026) | Each model keeps its own effort setting when you switch between them |
| Mid-session /effort no longer invalidates the prompt cache on Fable 5.1 | 2.1.268 (10 Sept 2026) | Changing effort mid-session stops costing you a full cache re-read |
| effort: frontmatter fixed on pinned-effort models | 2.1.268 (10 Sept 2026) | Custom commands, skills and subagents now respect their declared effort on Opus 4.7, Opus 4.8 and Fable 5 |
The prompt-cache fix deserves a highlight. Before 2.1.268, changing effort mid-session on Claude Fable 5.1 invalidated the prompt cache — so a quick "drop to low effort for this bit" could silently trigger a full-price re-read of your context. Per the changelog, that penalty is gone on Fable 5.1, which makes it genuinely practical to move effort up and down within one session as task difficulty changes. Cache behaviour is one of the biggest hidden levers in Claude costs generally — the Claude Code skill doctor guide covers the related question of what your loaded skills cost in context.
The frontmatter fix matters for anyone building custom commands and subagents: previously, an effort: declaration in a command, skill or subagent's frontmatter was ignored on models whose default effort is pinned — the changelog names Opus 4.7, Opus 4.8 and Fable 5. Now the declaration works, so a heavyweight review subagent can demand high effort whilst a formatting command runs cheap, regardless of the session default.
How To Set The Claude Code Max Effort Level
The changelog specifies two placements for the setting: top-level, or per model under modelSettings. A sensible rollout looks like this:
- Decide your default ceiling. For most day-to-day coding and automation work, medium-effort reasoning is enough; reserve the top levels for genuinely hard tasks. Set the top-level cap there.
- Add per-model exceptions under modelSettings. If one model in your rotation is your designated deep-reasoning model, give it a higher ceiling than the workhorse models.
- Let users work downward. Because the cap still allows lower levels, individuals keep the /effort command for dropping effort on easy tasks — and thanks to 2.1.268, each model now remembers the level they picked for it.
- Watch the spend for a week. Judge the cap by cost per completed task, not by vibes. If quality drops on hard tasks, raise the ceiling for the one model you use for them rather than for everything.
If you are newer to Claude Code and this is your first settings-file change, the learn Claude Code guide walks through where configuration lives and how the pieces fit; and if budget is the whole reason you are here, it is worth knowing the legitimate routes to free Claude Code usage before you optimise the paid kind.
📺 Watch: Run Claude Code Free Forever, Here's How!
Why A Cap Beats Telling People To Be Careful
Every team that runs agents at scale eventually learns the same lesson: policies that live in settings files get followed; policies that live in Slack messages do not. The Claude Code max effort level setting turns "please don't run everything on maximum" from a request into a guarantee, and it does so without the usual cost of central control — nobody is blocked from working, because the cap only bites in one direction.
It also composes well with the rest of the recent tooling. Claude Code has been steadily adding visibility and control features — /skill-doctor for context costs, output limits, per-model settings — and the direction of travel is clear: treat sessions as production workloads with budgets, not experiments. That is the same philosophy behind Agent OS, the operating layer for organising agent work into repeatable, measurable systems — and it is why harness-level controls matter as much as model choice. On the model-choice side, the Goldie Bench write-up covers how the current crop of models compare on real tasks, which is exactly the evidence you want when deciding which model earns a higher effort ceiling.
For teams on cloud providers, the uniform enforcement is the quiet win. A cap that worked on the direct API but not on Bedrock or Vertex would be a compliance gap, not a control. Per the changelog, this one applies everywhere, which means platform teams can finally write one effort policy for the whole organisation. If your Claude Code usage is spread across advisory-style planning sessions and heavy implementation runs, the Claude Code advisor mode guide shows a workflow where a capped, cheaper planning pass pairs naturally with a higher-effort build pass.
The Bottom Line On maxEffortLevel
Version 2.1.267 and 2.1.268 quietly turned effort from a loose per-session preference into a proper, provider-wide policy surface: a ceiling you set once, per-model defaults that persist, frontmatter that is honoured, and cache behaviour that no longer punishes you for adjusting mid-session. If you run Claude Code for anything that touches a budget, set the cap this week — it is the rare cost control that costs nothing to adopt.
If you want every upgrade like this turned into a working workflow for your business — with the configs already written — the AI Profit Boardroom includes the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls: get inside the AI Profit Boardroom. Want AI SEO help 1-on-1? Book a free SEO strategy session and we will build your roadmap together.
