Claude Code context limits: compaction, custom models, and task budgets
Understand what happens at Claude Code context limits, inspect compaction settings, and use CLAUDE_CODE_MAX_CONTEXT_TOKENS without confusing client and server capacity.
When Claude Code approaches its context limit, the issue is the working information available to the coding session, not necessarily a shortage of subscription usage. Compaction can summarize prior work so the task continues, but a client setting cannot enlarge the model server's actual context window. Distinguish those two layers before changing environment variables.
This guide addresses both “what happens when Claude Code reaches its context window limit” and the specific CLAUDE_CODE_MAX_CONTEXT_TOKENS setting. Documentation checked September 5, 2026. Client behavior changes between releases; record your installed version and verify the current model-configuration reference before copying settings from an older discussion.
Find the limit you actually reached
| Observation | Meaning | What to inspect |
|---|---|---|
| A compaction notice | The client is managing session context | Current context breakdown and compaction policy |
| A provider prompt-too-long error | The serving request exceeds a boundary | Upstream model and actual payload |
| A usage-reset message | An account usage window was reached | The relevant account and reset schedule |
| A gateway spend-cap message | A configured monetary budget was reached | The gateway policy, not context settings |
Claude Code's cost-management guide distinguishes context warnings from account and gateway limits. Do not interpret all of them as the same “token limit.” A good incident note records the wording, client version, configured provider, and task state without including secret credentials or the whole repository.
What compaction does to a coding task
The workflow explanation describes a context containing history, instructions, file content, and tool output. Compaction replaces older conversation material with a summary. The context walkthrough also explains that different instruction mechanisms survive or reload differently. A summary is not a verbatim archive of every observation.
For a long task, maintain a small recoverable state outside the conversation: the requested outcome, files intentionally changed, tests run and their results, decisions made, and unresolved blockers. Keep this state factual. “Implementation done” is not the same as “tests pass,” and neither proves a deployment reached production. Those distinctions help the next session resume from evidence rather than optimistic recollection.
When the agent continues after compaction, ask it to verify the next action against the actual files. A compacted note can say a function was updated while an interrupted edit never landed. A short read-only check costs less than debugging a chain built on a false starting assumption. Preserve source paths and test names so this check is easy.
Inspect before adjusting
Use claude --version to identify the release and the client's /context view to inspect what is occupying space. The relevant question is not simply the percentage full. Determine whether repeated file reads, large command output, loaded instructions, or the accumulated conversation dominate. Different causes suggest different ways to reduce the next request.
For a synthetic task, suppose the useful state needs 6,000 tokens, while repeated log output contributes 25,000. Increasing a limit might postpone the warning without improving the task. Extracting the relevant error, preserving the log path, and continuing with a compact evidence packet addresses the source of growth. Conversely, a task genuinely comparing many related files may need a larger verified backend window.
What CLAUDE_CODE_MAX_CONTEXT_TOKENS means now
The current model-configuration reference treats model identity carefully. For an unrecognized ID without a claude- prefix or [1m], the override applies directly while proactive compaction continues. An unrecognized [1m] ID needs the documented additional context-control setting. An ID beginning with claude-, or resolving to a Claude model, requires DISABLE_COMPACT for this override, disabling all compaction. These are separate cases, not interchangeable recipes.
Our recommendation is to resolve the exact case before setting anything. Record the identifier as the client sees it and the identifier the gateway serves. A friendly alias can conceal that difference. Avoid renaming models merely to make an environment variable appear effective; that can change client assumptions in ways unrelated to the actual server.
Most importantly, the variable declares a client assumption. It does not buy capacity, change model weights, or force a hosted API to accept a larger input. If you tell the client to assume more than the server allows, the request can still fail upstream. If you assume less, the client may compact earlier than necessary. Test the mapping with a bounded workload before adopting it for long unattended jobs.
Compaction thresholds and output budgets are different controls
The environment-variable reference separately documents CLAUDE_CODE_AUTO_COMPACT_WINDOW and CLAUDE_CODE_MAX_OUTPUT_TOKENS. One concerns the context capacity used for compaction calculations; the other concerns generation limits. Do not copy a large output allowance into the context setting or assume that changing one raises the other.
Choose an output budget based on the artifact needed. A concise diagnosis, a small patch, and a long design document have different requirements. During troubleshooting, change one control at a time and note the observed behavior. This keeps the experiment reversible and prevents several overlapping environment variables from hiding which setting is actually in effect.
Do not disable compaction solely to suppress a warning. Before using a setting that removes it, decide how the session will preserve state, how oversize requests will be detected, and when the work will move to a fresh session. Turning off a safeguard without a replacement workflow is not a capacity improvement.
A task-budget example across a compaction boundary
Consider a synthetic migration job: inspect two modules, update one adapter, and verify three tests. The task record should preserve the adapter's intended contract, the files in scope, and exact test outcomes. It does not need every successful shell listing. Before a new context starts, write a compact checkpoint that distinguishes completed changes from the next proposed action.
Now compare two hypothetical workflows. The first repeatedly asks the agent to rediscover the project after each long conversation. The second keeps a short, checked handoff and reloads only the relevant files. The second may use less repeated input, but the amount saved must be measured from actual usage rather than inferred from a shorter visible transcript. Compaction itself can involve model work and is not a refund for prior requests.
For an Ollama-backed session, collect the route and completed usage fields as described in the API accounting guide. Feed realistic monthly hosted consumption into the Ollama cash calculator only when that is the provider actually executing the requests. A Claude Code context setting does not turn an Ollama credit into a Claude subscription allowance.
Frequently asked questions
Will the agent forget everything after compaction?
Not everything, but you should not assume perfect preservation. The client retains a summarized working history and applies its documented instruction-loading behavior. Important constraints and acceptance evidence should be recoverable from your project records, with private material stored only where appropriate.
Should I always set the largest possible number?
No. First establish the server's real capacity, the client identity mapping, and the information the task needs. A larger assumption can increase the amount carried into requests without making the work more correct or the server more capable.
Why do older instructions disagree with this guide?
Client configuration evolves. Search-result summaries can lag behind current documentation, and model aliases can fall into different handling cases. Read the current page for your installed version rather than combining settings from unrelated examples.
Does a new conversation reset my bill?
No. A fresh session changes the working context; it does not undo resources already consumed or reset a provider's billing period. Keep context recovery and account accounting as separate procedures.
What if the backend still rejects the request?
Follow the context-overflow checklist. Preserve the exact upstream error, confirm the actual model mapping, and reduce the request that failed. Do not assume a client override overrides a server contract.