# Claude Code Max Effort: Configuration, Token Limits, and Best Practices

Claude Code max effort (`--effort max`) configures the terminal agent to use extended thinking budgets and autonomous tool loops for complex refactoring tasks. While high effort provides deep multi-file analysis, max effort pushes internal reasoning tokens to their limits and accelerates context compaction. Managing token consumption requires scoped retrieval, disciplined tool execution, and offloading reference corpuses to external workspaces.

Source: https://fast.io/resources/claude-code-effort-max/
Author: [Tom Langridge](https://fast.io/authors/tom-langridge/)
Last reviewed: 2026-11-04

## How Claude Code Effort Levels Shape Reasoning and Execution

Anthropic documents that standard Claude chat accepts up to 20 files at up to 500MB each, while Claude Projects accepts files up to 30MB each with unlimited file count, provided the total content fits within Claude's context window (verified in [Anthropic upload documentation](https://support.claude.com/en/articles/8241126-upload-files-to-claude)). In Claude Code, running at max effort (`--effort max` or `/effort max`) pushes reasoning and tool execution to the ceiling, which rapidly fills that very same context window. Managing an autonomous coding agent requires understanding how effort settings allocate tokens across thinking blocks, terminal commands, and file inspections.

In Claude Code, max effort (`--effort max`) configures the agent to use the highest available extended thinking budget and autonomous tool-execution loops to resolve complex architectural bugs before returning control to the user. Rather than functioning as a decorative prompt prefix, effort is a runtime behavioral control that dictates how aggressively the model reasons through ambiguities, tests alternative hypotheses, and executes verification steps.

| Effort Level | Reasoning Depth | Tool Call Autonomy | Primary Use Case | Token Consumption |
|---|---|---|---|---|
| `low` | Minimal internal thinking blocks | Single tool actions with early returns | Syntax corrections, file renames, trivial edits | Lowest token burn rate |
| `medium` | Moderate chain-of-thought analysis | Bounded multi-step tool calls | Routine implementation, unit tests, single-module updates | Balanced token usage |
| `high` | Deep multi-step reasoning (CLI default) | Iterative file exploration and test loops | Multi-file refactors, complex bug fixes, feature work | High token consumption |
| `max` | Highest reasoning budget without spending caps | Exhaustive search, self-correction, continuous verification | Intractable architectural bugs, legacy migrations, subtle race conditions | Maximum token burn rate |

Selecting an effort tier establishes the agent's persistence. At lower levels, Claude Code answers promptly with concise edits, asking the user for guidance whenever ambiguity arises. At max effort, the agent assumes complete ownership of the problem, exploring the dependency graph, running diagnostic commands, and attempting multiple distinct patches before presenting a finished solution.

### CLI Flags and Runtime Session Controls

You can establish effort levels when launching Claude Code or modify them dynamically inside an active terminal session. To start a fresh coding session configured for maximum reasoning depth, pass the `--effort` flag directly on the command line:

```bash
claude --effort max
```

If you are already running an interactive session and encounter a stubborn defect that resists standard debugging, switch effort dynamically without restarting your conversation:

```text
/effort max
```

The terminal interface confirms the transition immediately. You can drop back down to `/effort high` or `/effort medium` once the root cause is resolved to conserve tokens during subsequent routine edits.

For repositories that consistently demand deep autonomous reasoning, such as large monorepos with intricate build pipelines, persist your preference in your project's configuration file. Create or edit `.claude/settings.json` in the repository root:

```json
{
  "effortLevel": "high"
}
```

In programmatic environments or scripts invoking Claude through the Messages API, effort is defined within the `output_config` object, as detailed in the [Claude Platform effort documentation](https://platform.claude.com/docs/en/build-with-claude/effort):

```json
{
  "model": "claude-opus-4-7",
  "max_tokens": 64000,
  "output_config": {
    "effort": "max"
  }
}
```

Setting `output_config.effort` to `max` instructs the model provider to relax internal reasoning constraints, allowing the system to deploy broad reasoning chains across both thinking blocks and tool calling sequences.

## Why Extended Thinking and the 64k Reasoning Budget Consume Tokens

To understand max effort, developers must examine how extended thinking operates within the model's inference architecture. Anthropic documentation specifies that the effort parameter controls how many tokens Claude spends across reasoning thinking blocks and tool execution. Extended thinking introduces a dedicated reasoning space where Claude evaluates assumptions, constructs mental proofs, and traces execution paths before writing code.

Thinking tokens count toward the max_tokens limit for the turn, so the reasoning budget must leave room for the final code response. If your client requests a `max_tokens` ceiling of 8,000 tokens while extended thinking consumes 7,500 tokens exploring an algorithm, only 500 tokens remain for the actual patch. The model will truncate its response mid-file.

Max effort can allocate up to 64k tokens solely for internal reasoning before producing code. When paired with high output allowances, max effort grants Claude the cognitive runway to simulate entire runtime loops. The agent reads type definitions, compares interface contracts, detects potential null pointer dereferences, and drafts internal unit tests before modifying a single line on disk.

Effort functions as a behavioral signal rather than a rigid token minimum. If you set `--effort max` on a trivial task like fixing a misspelling in a README file, Claude Code does not artificially burn thousands of tokens pretending to think. Once the model validates the solution with certainty, it exits the thinking phase and executes the edit. The difference appears when ambiguity or complexity is present: medium effort might explore two plausible explanations before guessing, whereas max effort investigates seven alternative execution paths, verifies each against project imports, and confirms the fix against your test suite.

Every turn under max effort comprises five distinct token consumers:
1. System prompt overhead, tool definitions, and repository memory files (`CLAUDE.md`).
2. Rolling conversational history, containing user instructions and previous agent exchanges.
3. Raw command outputs from terminal tools, such as directory listings, build compiler logs, and file contents.
4. The extended thinking block, where multi-step internal deductions occur.
5. The visible output payload, consisting of structured tool invocations and final explanations.

## The Cost of Max Effort: Context Compaction and Token Bloat

Most developer guides treat effort as a simple quality dial, assuming that higher effort always produces superior outcomes. In production environments, this assumption breaks down. The primary operational bottleneck in Claude Code is not model intelligence; it is context window saturation.

Context compaction is triggered significantly faster under max effort due to repeated multi-file reads and tool outputs. Claude Code operates within an active 200,000-token context window. Every time the agent runs a terminal command, searches with grep, or inspects a source file, the returned text enters conversational memory. At max effort, Claude's heightened autonomy drives it to execute iterative discovery loops. Instead of inspecting a single handler, it inspects the router, the middleware chain, the database schema, and the background queue workers.

Consider an engineer investigating an intermittent database timeout. At default effort, Claude Code reads the database connection module, proposes increasing the connection pool size, and waits for user confirmation. At max effort, Claude Code reads the database module, greps for connection checkouts across 40 files, executes your local migration runner, inspects stdout logs, runs unit tests, reads the Docker Compose configuration, and queries system environment variables. Within four conversational turns, the agent can easily accumulate 150,000 tokens of raw tool output.

When conversational memory approaches the 200,000-token threshold, Claude Code initiates automatic context compaction. The runtime summarizes earlier messages, condenses previous tool outputs, and truncates historical exchanges to free up buffer space. 

Compaction introduces serious agent failure modes:
- Loss of Initial Constraints: A user may specify strict requirements in the first prompt, such as avoiding third-party dependencies or maintaining backwards compatibility with a legacy API. When compaction summarizes the opening turns into a brief abstract, subtle architectural constraints are frequently lost.
- Repetitive Failure Loops: If Claude Code ran a test suite that failed three turns ago, and that test output is compressed into a one-sentence summary, the agent may forget why the initial approach failed and attempt the exact same broken code modification again.
- Analysis Paralysis: When presented with a straightforward task, max effort can induce unnecessary second-guessing. The model may draft elaborate abstractions, invent edge-case handlers for scenarios that never occur in your application, or refactor unrelated helper functions, turning a five-minute bug fix into a sprawling diff.

## Steps to Prevent Context Window Exhaustion at Max Effort

Running Claude Code successfully at max effort requires active context discipline. You must prevent the agent from drowning its own context window in extraneous data before it completes its reasoning cycle.

Implement these operational steps to maintain high reasoning quality while keeping token consumption bounded:

1. Constrain File Inspections with Line Offsets: Never allow an agent to load thousands of lines of code when diagnosing an isolated function. Direct Claude Code to use line-bounded reads:
```text
Inspect src/services/billing.ts between lines 120 and 210 to evaluate the charge retry logic. Do not read the entire file.
```

2. Establish Comprehensive `.gitignore` Rules: By default, file search tools can sweep across generated directories, minified bundles, test coverage artifacts, and database dumps. Place or update your `.gitignore` file in your repository root to exclude heavy directories:
```text
dist/
build/
coverage/
*.log
*.sql
*.lock
package-lock.json
pnpm-lock.yaml
.git/
```

3. Pipe and Filter Shell Command Outputs: When asking Claude Code to run diagnostics, remind the agent to suppress excessive stdout. Running `npm test` across an entire enterprise suite can return 50,000 tokens of test results. Require targeted execution:
```text
Run npm test -- --grep "BillingService" and pipe output through tail -n 40 if failures occur.
```

4. Commit Progress and Restart Sessions: Do not let a single terminal session run indefinitely across multiple unrelated issues. When Claude Code successfully implements a complex feature or fixes a bug, commit the changes to Git. If the next task is distinct, start a fresh session with `/compact` or restart the CLI. A clean 200,000-token context window gives max effort the headroom it needs to reason effectively.

### When to Choose High Effort Over Max Effort

Because max effort accelerates context consumption, reserve it for tasks where deep autonomous exploration is indispensable. For the vast majority of software development, `/effort high` or `/effort medium` offers a superior balance of speed, cost, and accuracy.

Use `--effort max` for:
- Root-cause analysis on intermittent race conditions or multi-threaded deadlocks.
- Deep architectural refactors spanning multiple modules with circular dependencies.
- Security vulnerability remediation where timing attacks or injection vectors must be rigorously analyzed.
- Migrating legacy codebases across framework major versions where compilation errors trigger cascade failures.

Use `--effort high` or `--effort medium` for:
- Writing new API endpoints following established repository patterns.
- Drafting unit and integration test suites for existing business logic.
- Updating database schemas and writing corresponding migration scripts.
- Renaming symbols, updating dependencies, or refactoring single-file utilities.

Starting at medium or high effort allows you to verify that the agent understands the problem scope. If the initial implementation fails due to hidden domain complexities, you can escalate to `/effort max` with full awareness of the token trade-off.

## How Scoped Retrieval in Fast.io Resolves Context Bloat

The traditional pattern for providing context to Claude involves dumping reference files directly into the repository, pasting API specifications into chat prompts, or relying on project knowledge attachments. As established by Anthropic documentation, Claude Projects accepts files up to 30MB each with unlimited file count, but the total content must fit within Claude's context window. Attaching large documentation sets, API logs, and design documents directly to an agent session rapidly consumes available tokens, leaving inadequate space for max-effort reasoning blocks.

Teams frequently attempt local workarounds: storing gigabytes of PDFs, Swagger definitions, and historical incident logs in project subdirectories. When Claude Code searches these local files, its grep and read tools ingest massive chunks of text, triggering early context compaction. Standard consumer cloud storage tools like Google Drive, Dropbox, Box, and OneDrive store raw files, but they do not index document contents for programmatic AI agent retrieval.

The scalable architectural pattern decouples reference storage from the active coding context. Instead of storing large document corpuses locally inside your Git repository, maintain them in a [Fast.io workspace](/product/workspaces/).

Fast.io provides shared org-owned workspaces equipped with Intelligence Mode. When Intelligence Mode is enabled on a workspace, Fast.io automatically indexes documents for hybrid retrieval combining full-text search, semantic vector search, and structured metadata extraction. 

Claude Code connects directly to Fast.io through its remote Model Context Protocol (MCP) server over Streamable HTTP:

```bash
claude mcp add --transport http fast-io https://mcp.fast.io/mcp/code
```

After adding the server, run `/mcp` inside Claude Code to complete OAuth authentication in your browser, following the [Fast.io MCP setup guide](https://mcp.fast.io/docs). Alternatively, configure the connection in your repository's `.mcp.json` file:

```json
{
  "mcpServers": {
    "fast-io": {
      "type": "http",
      "url": "https://mcp.fast.io/mcp/code"
    }
  }
}
```

Once connected, Claude Code retrieves reference material through Fast.io's consolidated MCP toolset. When the agent needs to verify an external API payload schema or review architectural guidelines, it executes a targeted search query against Fast.io:

```json
{
  "query": "authentication token refresh cycle specifications",
  "files_scope": ["architecture-specs"]
}
```

Fast.io returns only the specific paragraphs and data structures relevant to the query. Instead of loading a 400-page enterprise specification into Claude Code's terminal history, the agent receives a 300-token excerpt with precise source citations. This preserves the local 200,000-token context window, allowing max effort to dedicate its reasoning budget entirely to analyzing code and executing tests.

Reference documents can be populated directly via upload or synchronized from existing enterprise repositories. Cloud Sync connects Google Drive, Dropbox, Box, and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand. Every stored file maintains full version history, and a detailed activity log records uploads, edits, moves, deletions, and permission changes across your team. Permissions are configured per organization, workspace, and share through role-based access, ensuring that coding agents access only the technical documentation relevant to their repository.

Creating an account is free; doing real work requires an organization on a paid subscription. Monthly plans start with a 14-day free trial, which requires a credit card. Plans are Starter at `$9.99/mo`, Business at `$49.99/mo`, and Enterprise at `$199.99/mo` on [Fast.io pricing](/pricing/). Teams exploring agent infrastructure can review [Fast.io storage for agents](/storage-for-agents/) to integrate remote MCP endpoints into their daily development workflows.

## Frequently asked questions

### What does claude code effort max do?

In Claude Code, max effort (`--effort max` or `/effort max`) configures the agent to use the highest available extended thinking budget and autonomous tool-execution loops. Under max effort, Claude explores multiple hypotheses, inspects dependencies across files, runs diagnostic terminal commands, and tests alternative patches before presenting a final solution to the user.

### Does high or max effort use more tokens in Claude Code?

Max effort uses significantly more tokens than high effort. While high effort provides deep multi-step reasoning suitable for everyday complex refactoring, max effort removes internal constraints on token spending, allowing Claude to allocate up to 64k tokens solely to extended thinking blocks and execute iterative file reads that accelerate context compaction.

### How do I prevent Claude Code from running out of context at max effort?

To prevent context exhaustion at max effort, enforce line-bounded file reads, configure `.gitignore` to exclude build artifacts and log files, pipe verbose test commands through stdout filters, and commit completed milestones to Git. To keep large architectural specifications from flooding active context, offload reference documents to an external Fast.io workspace and query them through MCP search.

### How do I switch effort levels during an active Claude Code session?

You can change effort levels on the fly by typing `/effort` followed by your desired tier in the interactive terminal, such as `/effort low`, `/effort medium`, `/effort high`, or `/effort max`. The agent updates its behavioral reasoning parameters immediately for subsequent prompts without requiring a session restart.

### When should I avoid using max effort in Claude Code?

Avoid using max effort for routine coding tasks, documentation edits, simple syntax fixes, or single-file updates. On straightforward assignments, max effort increases latency, burns token budgets on unnecessary internal deliberations, and risks overcomplicating code through analysis paralysis. Reserve max effort for elusive bugs, concurrency race conditions, and complex architectural redesigns.

## Sources

- [Claude Help Center: Upload files to Claude](https://support.claude.com/en/articles/8241126-upload-files-to-claude): Anthropic documents that Claude chat accepts up to 20 files at up to 500MB each, while Claude Projects accepts files up to 30MB each with unlimited file count, provided the total content fits within Claude's context window.
- [Claude Platform Docs: Effort](https://platform.claude.com/docs/en/build-with-claude/effort): Anthropic documentation specifies that the effort parameter controls how many tokens Claude spends across reasoning thinking blocks and tool execution.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.