How to Set Claude Code Effort Level Permanently Across Sessions

Apr 19, 2026

Configuration persistence for AI settings

The Problem

I set my Claude Code effort level to “max” in settings.json, started a long autonomous session, and then noticed something strange. After a few hours of productive work, I checked my effort level and it had mysteriously dropped to “high” without any warning.

The setting I had carefully configured had silently downgraded itself.

This is a known bug in Claude Code: settings.json cannot reliably persist max effort level. When you interact with the UI, max gets silently downgraded. Only the environment variable method provides reliable persistence for max effort.

Why Effort Persistence Matters

Every time I started Claude Code, I found myself typing /effort max manually. This worked for the current session, but the setting reset on restart. I was wasting time on repetitive configuration instead of actual work.

The effort level affects:

Thinking depth — how much internal reasoning Claude performs
Tool call appetite — willingness to explore and read extra files
Response length — detail and thoroughness of explanations
Agentic persistence — planning ahead autonomously

Setting this once and having it survive across sessions means consistent behavior and less friction.

The Two Persistence Methods

I discovered two methods with different reliability:

Method 1: settings.json (Works for low/medium/high/xhigh)

{
  "effortLevel": "high"
}

Location: ~/.claude/settings.json

This works reliably for low, medium, high, and xhigh. But it does NOT reliably work for max due to a bug that causes silent downgrade when you interact with the UI.

Method 2: Environment Variable (Required for max)

# For max effort (required due to settings.json bug)
export CLAUDE_CODE_EFFORT_LEVEL=max

# Alternative: for high effort
export CLAUDE_CODE_EFFORT_LEVEL=high

Set in your shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile). This is the only reliable method for max effort.

The Max Effort Bug I Discovered

I spent an afternoon debugging why my max setting kept disappearing. Here’s what I found:

SESSION START:
  settings.json has "effortLevel": "max"
  Claude launches at max effort
  Everything looks correct

UI INTERACTION (any click, menu, etc):
  UI silently downgrades max to xhigh/high
  No warning or notification
  Setting appears correct but behavior changes

VERIFICATION:
  /effort command shows actual level
  "Current effort level: high" (not max!)
  Configuration file still shows max
  But actual behavior is downgraded

The Reddit thread confirmed this as a “known bug” affecting max effort persistence via settings.json. The environment variable bypasses this bug entirely.

My Trial-and-Error Journey

I tried multiple approaches before finding the solution:

Attempt 1: Interactive Command

/effort max      # Set to max for current session

This worked for the session, but reset on restart. Not persistent.

Attempt 2: CLI Flag

claude --effort max

Same problem—per-session only. Reset on next launch.

Attempt 3: settings.json (The Failed Approach)

{
  "effortLevel": "max"
}

I edited ~/.claude/settings.json directly. The setting appeared to work initially, but silently downgraded after UI interaction. I wasted hours debugging this.

Attempt 4: Environment Variable (The Solution)

export CLAUDE_CODE_EFFORT_LEVEL=max

This finally worked reliably. The setting persists across sessions and survives UI interactions.

The Complete Configuration

Here’s my recommended setup for max effort users:

Step 1: Add to Shell Profile

# Claude Code persistent effort setting
export CLAUDE_CODE_EFFORT_LEVEL=max

# Claude Code persistent effort setting
export CLAUDE_CODE_EFFORT_LEVEL=max

Step 2: Apply Changes

source ~/.zshrc  # or ~/.bashrc

Step 3: Verify in Claude Code

/effort
# Should show: "Current effort level: max"

Decision Matrix: Which Method to Use

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   EFFORT LEVEL   │ RECOMMENDED METHOD        │ WHY                  │
│   ───────────────┼──────────────────────────┼───────────────────── │
│   low            │ settings.json OR env var  │ Both work reliably   │
│   medium         │ settings.json OR env var  │ Both work reliably   │
│   high           │ settings.json OR env var  │ Both work reliably   │
│   xhigh          │ settings.json OR env var  │ Both work reliably   │
│   max            │ env var ONLY              │ settings.json bug    │
│   auto           │ Don't persist             │ Resets to default    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Key insight from spencer_kw on Reddit: “if you’re on a max plan, set CLAUDE_CODE_EFFORT_LEVEL=high in your shell profile. massive difference on complex tasks.”

Troubleshooting

Check Current Effort Level

/effort
# Shows current level and opens interactive slider

Check Environment Variable

echo $CLAUDE_CODE_EFFORT_LEVEL
# Should output: max (or your chosen level)

Check settings.json

cat ~/.claude/settings.json
# Look for "effortLevel" key

If settings.json shows max but /effort shows a lower level, you’re experiencing the bug.

Common Mistakes

Mistake 1: Using settings.json for Max

WRONG:
  "I'll set max in settings.json for persistence."
  Result: Silent downgrade after UI interaction.
         Wasted time debugging disappearing setting.

RIGHT:
  "Use CLAUDE_CODE_EFFORT_LEVEL=max environment variable."
  Result: Reliable persistence, survives all interactions.

Mistake 2: Not Setting in Shell Profile

WRONG:
  export CLAUDE_CODE_EFFORT_LEVEL=max
  # Just running this in terminal

RIGHT:
  # Add to ~/.zshrc or ~/.bashrc
  export CLAUDE_CODE_EFFORT_LEVEL=max
  source ~/.zshrc
  Result: Persists across terminal restarts.

Mistake 3: Assuming All Levels Work the Same

WRONG:
  "All effort levels must work the same way."
  Result: Using settings.json for max, hitting the bug.

RIGHT:
  "Max requires different method due to bug."
  Result: Choose method based on level.

Per-Session Alternatives

If you don’t want permanent settings, you can still set effort per-session:

Interactive Command

/effort max      # Set to max for current session
/effort high     # Set to high for current session
/effort          # Open interactive slider (no argument)
/effort auto     # Reset to model default

CLI Flag at Launch

claude --effort max     # Launch with max (one session only)
claude --effort high    # Launch with high
claude --effort medium  # Launch with medium

These do NOT persist—resets on next Claude Code launch.

Summary

Persist Claude Code effort level with the right method:

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   FOR low/medium/high/xhigh:                                        │
│   → settings.json: { "effortLevel": "high" }                        │
│   → OR env var: export CLAUDE_CODE_EFFORT_LEVEL=high                │
│   → Both work reliably                                               │
│                                                                     │
│   FOR max:                                                          │
│   → env var ONLY: export CLAUDE_CODE_EFFORT_LEVEL=max               │
│   → settings.json has known bug                                     │
│   → Silent downgrade after UI interaction                           │
│                                                                     │
│   CRITICAL WARNING:                                                 │
│   → settings.json cannot reliably persist max                       │
│   → Use environment variable for max effort                         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

The max effort bug is subtle but significant. I wasted hours before discovering it. If you need max effort consistently, use the environment variable method—it’s the only reliable approach.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit: Claude Code effort levels discussion
👨‍💻 Anthropic Claude Code Documentation
👨‍💻 Claude Code Environment Variables Reference

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!