How to Cap Claude Code Reasoning Effort

The short answer

Upgrade to Claude Code 2.1.267 or later, then put "maxEffortLevel": "medium" in the settings file that matches the people and projects you want to govern. Use ~/.claude/settings.json for your own global ceiling, .claude/settings.json for everyone working in one repository, or managed settings for an organization-wide rule.

The setting accepts low, medium, high, xhigh, or max. A value of max means that source places no ceiling on effort. Leaving the key unset also means no cap.

This is a speed limiter, not a fuel card. It limits how hard Claude may reason on a request. It does not set a token allowance, a dollar quota, or a subscription usage limit. Measure those separately with /usage, the Claude Console, or Claude Code OpenTelemetry.

What maxEffortLevel actually changes

effortLevel and maxEffortLevel do different jobs. An effort level is the requested setting for a session or model. The maximum effort level is the boundary that request cannot cross.

If the cap is medium, a developer can still choose low or medium. Asking for high, xhigh, or max runs at medium instead. The cap also catches effort requested through /effort, the /model picker, --effort, CLAUDE_CODE_EFFORT_LEVEL, and the model's default. Claude Code applies it on the client before each request, so the same policy works when the model traffic goes through Anthropic, Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry.

The crucial rule is easy to miss: the lowest cap across all loaded scopes wins. Normal Claude Code settings usually follow a hierarchy, with managed settings above command-line settings, project files, and user settings. maxEffortLevel is a restrictive exception. A lower project cap still wins even if a managed or user source permits more.

Set a global cap, a model exemption, and a stricter project cap

First check claude --version. If it is older than 2.1.267, run claude update before adding the key.

For a personal ceiling across every repository, put this in ~/.claude/settings.json:

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

The top-level value caps every supported model at medium. The Sonnet 4.6 entry replaces that top-level value for Sonnet inside this user file only. Its max value does not force Sonnet to run at maximum effort. It means this particular source does not cap that model.

Now add a tighter rule for one repository in .claude/settings.json:

{
  "maxEffortLevel": "low"
}

The effective result is deliberately strict:

The model exemption does not punch through the project rule. It only cancels the user source's medium cap for Sonnet. This is the mistake most likely to create a false sense of exemption.

For a company policy, deploy the same top-level key through managed settings. That applies the ceiling to the people covered by that managed source on any supported provider. If an Enterprise role also has an effort limit, Claude Code applies whichever cap is lower.

Verify the ceiling before trusting it

A valid JSON file is not proof that the intended cap won. Verify both the loaded sources and the applied level.

1. Run /status inside Claude Code. The Setting sources line confirms that User settings, Project settings, and any Managed settings were loaded. It does not tell you which source supplied each individual key.
2. Run claude doctor if a source is missing or a new key appears to be ignored. It lists rejected settings entries. The published JSON schema can lag a new CLI release, so an editor warning alone is not the verdict.
3. Check the session header beside the model name. Claude Code displays the current effort there and briefly in the footer when it changes.
4. In the example repository, request /effort max. The project-level low ceiling still applies. A higher request cannot raise it.
5. For non-interactive fleets, inspect the effort attribute on claude_code.cost.usage and claude_code.token.usage. It records the level applied to each request alongside the model and query source.

That last check matters on Bedrock, Google Cloud, and Foundry. The policy is enforced by Claude Code before the provider receives a request, while the telemetry shows what Claude Code actually applied.

Test quality and spend as two separate tracks

Do not roll out a medium or low cap because the label sounds economical. Use a routine task your team already understands and compare matched runs.

A useful fixture is a small repository with one failing parser test. Give each run the same model, commit, prompt, permissions, and tool access: fix the edge case, add a regression test, run the suite, and report the changed files. Run the uncapped baseline, restore the clean fixture, then run the capped condition.

Score the outcome before looking at cost:

The decision metric is cost per accepted task, not tokens per response. A lower-effort run that needs a second review or repair pass can cost more than a clean higher-effort run. The same logic applies to the broader Claude effort-level sweep, but the new setting makes the chosen upper bound enforceable in Claude Code.

Seven places an effort ceiling pays

These use cases are ranked by who gets the clearest operational return.

1. Platform teams governing routine work

A platform team supporting 20 or 200 developers could set medium in managed settings, keep lower levels available, and reserve policy changes for measured exceptions. The payoff is not merely fewer tokens. It is a consistent default boundary across laptops, IDE sessions, and cloud-provider routes, which makes cost and quality comparisons usable.

2. FinOps owners with API-billed Claude Code

A FinOps lead could combine a managed ceiling with OpenTelemetry grouped by effort, model, team, and cost center. The workflow is simple: observe the uncapped baseline, introduce the cap to a pilot group, and compare cost per accepted task. This replaces arguments about which effort level feels expensive with a report tied to delivered work.

3. Enterprises using Bedrock, Google Cloud, or Foundry

A regulated company may route models through its chosen cloud for procurement or data controls. The Claude Code client applies maxEffortLevel before every request, so the organization can use one effort policy across those providers. The payoff is policy parity without waiting for every provider console to expose the same control.

4. CI maintainers running repetitive fixes

A team that invokes Claude Code for dependency bumps, formatting repairs, test maintenance, or documentation changes could cap those repositories at low or medium. The exact level should come from task fixtures, but once quality holds, the ceiling prevents a flag, skill, or model default from escalating routine automation into a deeper reasoning mode.

5. Monorepo owners separating routine and difficult work

A monorepo owner could keep a personal medium ceiling, commit a lower shared cap in a documentation or generated-code repository, and leave a harder systems repository at the broader limit. Each repository carries its own boundary. The payoff is a cost policy that follows the work instead of relying on every developer to remember a command.

6. Consultancies switching between client repositories

A consultant could use a personal medium ceiling as the baseline and let each client repository impose a stricter shared setting. That reduces configuration drift when the same laptop moves between a small content site, a mature application, and a cost-sensitive maintenance contract. The project file documents the intended operating mode for the next person too.

7. Staff engineers preserving a narrow model exception

A staff engineer could exempt one model from a source's global cap with modelSettings, then keep a different lower cap in a safety-critical repository. This gives the model room where the source permits it without turning an exemption into a universal bypass. The payoff is a precise exception that remains subordinate to stricter project or organizational policy.

What is worth building around this

1. Effort regression gate, the strongest opportunity

Build a CLI and CI check that runs a repository's accepted-task suite at allowed effort levels, then reports pass rate, review defects, duration, tokens, and cost. Engineering platform teams would pay because the cap creates an immediate quality question: how low can routine work go before repair work erases the savings?

The demand signal is unusually commercial. ai code review has an estimated 1,300 U.S. searches a month and a $62.38 CPC. The smallest sellable version is a local runner plus a GitHub check that compares two effort profiles on the same clean fixture and blocks a policy change when required tests or review rules regress.

The catch is the benchmark. A generic coding score is easy to copy and weakly connected to a buyer's repository. The defensible part is the team's private task set, review rubric, and history across model updates. Without that data, this is just another dashboard.

2. Claude Code effort policy linter

Build a read-only policy inspector that maps user, shared project, project-local, command-line, and managed sources into one per-model ceiling table. Platform and security teams would use it to catch a max exemption that was assumed to be global, a lower project cap that unexpectedly wins, or a fleet still running before 2.1.267.

claude code has an estimated 550,000 U.S. searches a month, and the live question set includes “What effort level should I use for a Claude code?” That volume is broad rather than purchase-ready, but the configuration confusion is direct. An MVP only needs source discovery, version detection, JSON validation, and an explanation of the lowest winning cap.

The catch is platform risk. Anthropic could add a native effective-settings inspector. A durable product would need policy drift alerts, fleet inventory, and evidence for audits, not merely a prettier settings screen.

3. Effort-aware Claude Code spend monitor

Build a focused OpenTelemetry dashboard that joins the applied effort attribute with tokens, cost, model, query source, repository, and quality checks across Anthropic and cloud-provider deployments. FinOps and developer-experience teams would pay for the connection between policy and outcome, not another token total.

llm observability has an estimated 590 U.S. searches a month and a $37.45 CPC. Existing pricing confirms a budget line: Datadog Agent Observability starts free for 40,000 LLM spans, while Pro starts at $160 per month for 100,000 spans. A focused MVP could ship as an OpenTelemetry collector preset, a cap inventory, and three views: applied effort, cost per accepted task, and regressions after a model or policy change.

The catch is competition and causality. Observability vendors already collect tokens and costs, and a lower bill after a cap does not prove the cap caused it. The product needs matched evaluations or change-point evidence to earn trust.

The effort regression gate is the best of the three. Its demand sits closest to a paid engineering decision, and its private evaluation history becomes more valuable each time Anthropic changes a model or effort calibration.

What the cap does not solve

An effort ceiling does not guarantee a smaller bill. Effort affects output tokens, tool behavior, and thinking, but model choice, codebase size, cache behavior, and parallel automation still matter. Claude Max and Pro subscribers have usage included in their plan, so the /usage session cost is not their bill.

It does not make low safe for every coding task. Anthropic explicitly recommends testing the workload, and the same effort name is calibrated differently across models. A medium run on one model is not a fixed quantity of reasoning that can be compared mechanically with medium on another.

It does not create an absolute bypass for a model. A per-model max entry removes only the top-level cap from the same source. Another source can still impose a lower ceiling, and an organization effort limit can be lower again.

Finally, /status confirms which files loaded, not the winning file for every key. For automation, the applied effort telemetry attribute is the cleaner record.

The Monday move

Pick one routine repository task next week. Capture an uncapped baseline, add a user-level medium cap, add the documented Sonnet exemption, then put low in the shared project file. Confirm the loaded sources and session-header effort, repeat the task from the same clean fixture, and compare acceptance quality before /usage cost. If quality holds, promote the tested ceiling to the right shared or managed scope. If it fails, raise or remove the strictest cap for that workload and keep the evidence.

If you want an effort policy, evaluation gate, and cost telemetry built around your engineering workflow, see AI production systems.