CLAUDE_CODE_MAX_OUTPUT_TOKENS: Control Output Length

The claude code max output tokens setting is controlled by the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable, which caps how many tokens Claude Code can produce in a single response. Raise it for longer, uninterrupted answers; lower it to reduce cost and latency. Set it in your shell or in settings.

Variable name, settings precedence, and per-model output ceilings verified 31 July 2026 against Anthropic's Claude Code settings documentation.

If you have ever watched Claude Code stop mid-file, cut off a long refactor, or return "output limit reached," you have run into the output token ceiling. The good news is that this ceiling is configurable. The claude code max output tokens value is not fixed — you decide it, within the limits of the model you are running. Claude Code currently runs on the latest models like Claude Opus 5 and Claude Sonnet 5, and this guide is reviewed regularly so the steps stay accurate. Here is what it covers. We put this through its paces on our own setup first, so the notes below reflect what really happened, not what should happen.

• What the setting actually does
• Why you would change it, and when it helps
• How to set it correctly so the change actually sticks

What CLAUDE_CODE_MAX_OUTPUT_TOKENS actually controls

It sets the max_tokens value on every request Claude Code sends, capping how much the model may write in one turn. That is output capacity only — the context window governing what it can read is an entirely separate limit.

Every request Claude Code sends to the model carries a max_tokens value. That number is the hard cap on how many tokens the model may generate in its reply for that turn. The claude code max output tokens setting is simply how you control that max_tokens from outside the app, through the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.

It is important to separate two different limits that people constantly confuse:

• Output tokens — what the model writes back in one response. This is what claude code max output tokens governs.
• Context window — everything the model can read at once: your prompt, files, tool results, and conversation history combined. That is input capacity, not output capacity.

These are independent. A large context window lets Claude see a huge codebase; the output cap decides how much it can say per turn. If you want the full picture of how input capacity works, our explainer on the Claude context window covers it in depth, and you can watch consumption in real time with the techniques in our guide to checking token usage in Claude Code. When you hear "the response got cut off," the culprit is almost always the output cap, not the context window.

So the mental model is clean: claude code max output tokens = the maximum size of one answer. Nothing more, nothing less.

Why you would change the claude code max output tokens value

Three reasons override a sensible default: raise it when long generations truncate mid-file, lower it to trim cost and latency in CI or shared environments, and align it with whatever ceiling a proxy or gateway imposes.

Most people never touch this setting, and that is fine. Claude Code ships with a sensible default. But there are real reasons to override it.

Raise it when responses get truncated. Big jobs — generating a long module, writing extensive tests, producing detailed documentation, or migrating a large file in one pass — can bump against the ceiling. When that happens the reply ends abruptly. Increasing the claude code max output tokens value gives the model room to finish in a single turn instead of stopping short.

We run into exactly this while writing and revising long-form articles for this site inside Claude Code. When a single draft or a big multi-section rewrite is the goal, a default-sized cap tends to stop the response partway through a file, and we end up nudging it to continue over and over. Bumping the claude code max output tokens value up for those sessions turned that stop-start dance into a single clean pass — but we drop it back down again for routine edits, where a tighter ceiling keeps turns fast and cheap.

Lower it to control cost and latency. Output tokens are typically the more expensive half of a request, and longer generations take longer to stream. If you want tighter, cheaper, more predictable answers — say in a CI pipeline or a shared team environment — dropping the claude code max output tokens value keeps each turn compact and fast.

Fit provider or gateway limits. If you route Claude Code through a proxy, gateway, or an alternate provider, that backend may impose its own output ceiling. Aligning your claude code max output tokens setting to what the provider accepts avoids errors caused by requesting more than the endpoint allows.

In short: raise it for completeness, lower it for economy. The right max output tokens value depends entirely on the kind of work you do.

How to set CLAUDE_CODE_MAX_OUTPUT_TOKENS

Three routes, temporary to permanent: export it in the current shell, append the export to ~/.zshrc or ~/.bashrc so it survives reboots, or place it in the env block of settings.json so it applies however claude was launched.

There are three practical ways to apply the setting, from most temporary to most permanent.

1. Export it for the current shell session

The quickest method is to export the variable before you launch Claude Code:

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
claude

This applies to every Claude Code session started from that same terminal, and it disappears when you close the shell. It is ideal for a one-off big generation where you temporarily want more room. On Windows PowerShell the equivalent is $env:CLAUDE_CODE_MAX_OUTPUT_TOKENS = "8192" before running claude.

2. Persist it in your shell profile

To make the value survive reboots and new terminals, add the export line to your shell startup file — ~/.bashrc, ~/.zshrc, or the equivalent:

echo 'export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192' >> ~/.zshrc

Open a fresh terminal (or source the file) and every future session inherits the max output tokens value automatically. This is the cleanest option for a personal machine where you always want the same ceiling.

3. Put it in Claude Code's settings env block

Claude Code also reads environment variables from an env block inside its settings.json. Because it reads these at startup, they take effect no matter how claude was launched — even if a given terminal never exported the variable:

{
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "8192"
  }
}

This is the most reliable approach for consistent, project- or user-wide behavior, and it is what the official Claude Code settings documentation recommends for variables you want applied every time. If you are new to configuring the tool, our walkthrough on Claude Code installation shows where these settings files live, and the broader Claude Code CLI documentation covers the full settings surface.

Whichever route you choose, restart Claude Code after changing the value so it re-reads the environment.

Defaults and upper bounds

Two facts kill the temptation to guess at magic numbers: leaving the variable unset gives you a sensible built-in default, and no value you choose can exceed the running model's own per-response ceiling — it is silently clamped.

Two facts matter here, and both argue against guessing at magic numbers.

First, if you never set the variable, Claude Code uses a sensible built-in default. You do not need to configure max output tokens for normal work — the default handles typical prompts comfortably.

Second, you cannot exceed the model's own maximum output limit. Each Claude model has a ceiling on how many tokens it can generate per response. Setting max output tokens to an enormous number does not unlock more than the model physically supports; you are simply choosing a value up to that model ceiling. If you switch models, the effective maximum can change with it — see how to change the model in Claude Code if you want to move to a model with a larger output allowance. Because these numbers shift as models evolve, always confirm the current per-model limits in the official docs rather than hard-coding a figure you read once.

A related knob: thinking tokens

MAX_THINKING_TOKENS governs the reasoning budget before an answer, not the answer's length. Short replies call for the output variable; shallow reasoning calls for the thinking budget. Adjust them independently.

There is a separate variable, MAX_THINKING_TOKENS, that controls the model's reasoning budget — the internal extended thinking it does before answering — not the length of the final reply. It is easy to conflate the two because both deal in tokens, but they are distinct: Max output tokens caps the visible answer, while the thinking budget governs hidden reasoning. If your answers are short, adjust the output variable; if you want deeper deliberation, that is the thinking budget's job. Treat them separately.

Quick reference: which value for which goal

Five goals, five settings: a higher value for long files, a lower one for cheaper turns, the provider's stated maximum behind a gateway, unset for everyday coding, and a one-session export for a single oversized job.

Use this table as a starting point, then tune to your workflow. The exact numbers you pick depend on your model and provider; treat these as directional.

Troubleshooting the claude code max output tokens setting

Four symptoms account for nearly every complaint: replies that stop mid-file, costs that climb faster than expected, a value that appears to be ignored entirely, and simple uncertainty about where the real ceiling sits.

Responses keep cutting off. Raise the max output tokens value, or simply ask Claude to "continue" — it will pick up where it stopped. For very large outputs, splitting the task into smaller steps is often more reliable than one giant turn, a habit reinforced in our Claude Code tips and tricks.

Costs or latency are too high. Lower the value. A tighter ceiling keeps each turn compact, which is especially useful in automated or shared setups where predictable output size matters.

The value seems ignored. This is the most common complaint, and it is almost always an environment problem. Check that you exported the variable in the same shell that launched claude, that the name is spelled exactly CLAUDE_CODE_MAX_OUTPUT_TOKENS (no typos, all caps), and that you restarted the session after changing it. If you set it in settings.json, confirm the file is valid JSON and in the right location. Remember too that you cannot exceed the model's own maximum, so a very high value is silently clamped to what the model supports.

You are unsure what the ceiling even is. Rather than trust a blog's number, confirm against Anthropic's own material — the context windows and token limits reference documents how input and output limits relate across models. Pair that understanding with a solid grasp of what Claude Code is and you will rarely be surprised by an output cap again.