Context windows and token limits for coding agents

A coding agent’s context window is the token budget the model rereads every turn: system prompt, CLAUDE.md or AGENTS.md, tool definitions, file reads, command output and conversation. When it fills, the agent compacts older material, and instructions it was following can quietly disappear. Measuring usage and deciding when to compact, clear or delegate keeps the output trustworthy.

You are forty minutes into a debugging session. The agent has read twelve files, run the test suite six times, and found the bug. You ask for the fix, and it edits the wrong module, reintroduces the approach you rejected twenty minutes ago, and skips the regression test your project rules require. Nothing crashed; the session compacted, and the constraints you stated early did not survive the summary. This page is for developers who drive agents for long sessions and for tech leads who write the shared rules those sessions depend on.

What you get from managing the context window deliberately

• A way to see what is in the window right now, in each tool, instead of guessing.
• A decision rule for when to compact, clear, fork or hand work to a subagent.
• Two copy-paste prompts: a scoped exploration and a handoff note that survives any reset.
• A compaction hook that re-injects your non-negotiable rules automatically.
• A check that proves the agent still holds your constraints after a reset, without re-reading its whole transcript.

What fills a coding agent’s context window?

The window is not only your conversation. Every turn resends everything the agent currently holds, so the largest consumers are the ones you do not see in the terminal:

Consumer	Loaded when	How to shrink it
System prompt, environment info	Always, first	You cannot; it is fixed overhead
CLAUDE.md / AGENTS.md and rules	At session start, and again after compaction	Prune the file; move reference material into skills or path-scoped rules
MCP tool definitions	At start or on demand, depending on the tool	Remove servers you do not use; see reducing MCP token cost
File reads	Each time the agent opens a file	Name the exact files; ask for the one function, not the whole file
Command output	Each test, build or grep run	Filter output (--silent, pipe logs through tail -50); fail fast
Conversation history	Grows every turn	Compact with a focus, or clear between tasks

Claude Code’s own context documentation names file reads as the largest consumer in a typical session (code.claude.com, context-window, checked 2026-09-26). That matches what you will see in /context on a real repository: the agent’s exploration, not your prompts, fills the window.

How big is the window, and why is “bigger” not the fix?

Window sizes depend on the model and the host, and they change with every release. The models hub holds the current figures; two host details matter for this page:

• Claude Code: from v2.1.280 (the latest channel), Claude Code defaults to Claude Opus 5.5, with a 1M-token window on the Anthropic API. On the stable channel (v2.1.274 on 2026-09-26) the default is still an older model. By default, a session on a 1M-window model auto-compacts at about 967K tokens (Claude Code model-config docs, checked 2026-09-26).
• Codex gives its default model a working window that is smaller than the model’s maximum. You can raise it with model_context_window in ~/.codex/config.toml, up to the ceiling the model allows; see the models hub for the current figures (Codex model catalog, checked 2026-09-26).

A larger window postpones compaction; it does not make the model attend equally well to everything in it. Instructions from early in a very long session compete with hundreds of thousands of tokens of file contents and logs, and the model’s adherence to them can degrade well before any limit. Treat the window as a budget you spend on the task, not as storage.

How do you see context usage in Claude Code, Codex and Cursor?

Measure before you manage. Each tool exposes usage differently.

Claude Code

Run /context at any point. It draws current usage as a colored grid, broken down by category (system prompt, memory files, tools, messages), and lists optimization suggestions such as context-heavy MCP tools or an oversized CLAUDE.md.

To keep the number on screen, add a status line to .claude/settings.json (or ~/.claude/settings.json for all projects). Claude Code pipes session JSON to the command, including context_window.used_percentage:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

The command needs jq on your PATH.

If you would rather see cost next to context, ccusage (npm ccusage) ships a ready-made status line:

{ "statusLine": { "type": "command", "command": "npx -y ccusage statusline" } }

The status line runs outside the model, so it adds no tokens to the context window; npx -y downloads the package the first time it runs.

Codex

Run /status in the Codex TUI. It shows the current session configuration and token usage. Run /statusline to choose which items the TUI keeps in its status line.

To change the window or the compaction point for one run, pass config overrides on the command line:

# terminal: raise the working window and compact earlier, for this session only
codex -c model_context_window=400000 -c model_auto_compact_token_limit=300000

Put the same keys in ~/.codex/config.toml to make them permanent. Checked against Codex CLI 0.157.1 and its config schema.

Cursor

This page does not name Cursor’s context indicator or summarization thresholds, because they change by model; check the model picker for the current window.

The techniques on the rest of this page work the same way in Cursor: one chat per task, the exact files named in the prompt, a handoff note on disk, and a fresh chat when the current one has drifted. Cursor’s agent can also delegate to subagents (Cursor docs, checked 2026-08-28), which keeps large exploratory reads out of the main chat.

When should you compact, clear, fork or delegate?

Decide by what you still need, not by how full the meter is:

Situation	Action	Claude Code	Codex	Cursor
Same task, long history, decisions still matter	Compact with a focus	/compact <what to keep>	/compact	Write the handoff note, then start a new chat
Only part of the history is noise	Summarize a slice	/rewind → Summarize from here or Summarize up to here	No slice summarize in Codex CLI 0.157.1: write the handoff note, then /compact or /new	Write the handoff note, then start a new chat
Next task is unrelated	Clear	/clear	/new	New chat
You want to try another approach without losing this one	Branch	/branch	/fork	Start a new chat from the handoff note
A side task would flood the window with reads or logs	Delegate	A subagent: its reads stay in its own window and only the summary returns	Subagents (/subagents switches between them)	Subagent (Cursor docs, checked 2026-08-28)
A quick question about the session	Ask on the side	/btw <question>, which does not add to the conversation	/btw <question> (a side conversation in an ephemeral fork; Ctrl+C returns to the main thread)	Ask in a separate chat

Two rules make this table work in practice:

1. Compact before a phase change, not when the meter forces you. Auto-compaction guesses what matters; a focused /compact after “diagnosis done, starting the fix” keeps what you choose. To compact earlier by default, lower the auto-compact window in Claude Code with /autocompact 500k, or set model_auto_compact_token_limit in Codex. /autocompact is saved to your user settings, so it applies to every project; /autocompact auto restores the default. Use claude --autocompact 500000 for a single session.
2. Anything that must outlive a reset lives on disk. Plans, acceptance criteria and progress notes in files survive compaction, /clear and a new session. Conversation-only decisions do not.

Run a long task without losing the plot

This is the workflow for a task that will outgrow one window: a multi-file fix, a migration, a feature with several phases.

1. Scope the session to one outcome. Write the outcome and its acceptance criteria into a file the agent can re-read, for example .agent/handoff.md (add the directory to .gitignore if you do not want it committed). One session, one outcome; the next outcome gets a fresh session.

2. Explore cheaply. Ask for targeted reads and a short written summary instead of letting the agent open whole directories. The first prompt below does this. For a broad investigation, hand it to a subagent so the file contents never enter your main window.

   Copy-paste prompt: context-cheap exploration

   I need to understand how subscription cancellation works in this repo before changing it.
   
   Rules for this exploration:
   - Search first (ripgrep or your search tool); do not open whole directories.
   - Read only the functions on the cancellation path, not entire files.
   - Follow the path through at most four files. Ignore generated clients and anything under legacy/ or v1/.
   - Skip test output unless a test fails.
   
   Then write a summary of no more than 15 lines to .agent/handoff.md under "## Cancellation flow":
   entry point, the functions called in order (file:line), where state is persisted, and open questions.
   Do not change any code yet.

3. Checkpoint at each phase boundary. When diagnosis is done, have the agent update the handoff note, then compact with a focus on it:

   /compact Keep the acceptance criteria, the files changed so far, the rejected approaches and why, and the exact test command. Drop exploration output and old test logs.

   Copy-paste prompt: handoff note that survives any reset

   Update .agent/handoff.md so a fresh session with no memory of this conversation can continue the work. Use exactly these sections:
   
   ## Goal and acceptance criteria
   (copy them verbatim from the top of this file; do not reword)
   ## Done
   (files changed, one line each, with the reason)
   ## Decisions and rejected approaches
   (what we chose, what we ruled out, and why)
   ## Current state
   (the exact test command, and which tests pass and fail right now)
   ## Next step
   (one concrete action)
   
   Keep it under 60 lines. Do not include code blocks longer than 5 lines; reference file:line instead.

4. Make your rules survive compaction automatically. In Claude Code, the project-root CLAUDE.md is re-injected after compaction, but path-scoped rules and nested CLAUDE.md files are summarized away until the agent reads a matching file again (Claude Code context-window docs, checked 2026-09-26). For rules that must hold for the whole task, add a SessionStart hook with the compact matcher to .claude/settings.json; Claude Code adds the command’s output to the compacted context:

   {
     "hooks": {
       "SessionStart": [
         {
           "matcher": "compact",
           "hooks": [
             { "type": "command", "command": "cat .agent/handoff.md 2>/dev/null || true" }
           ]
         }
       ]
     }
   }

   In Codex, re-inject the file by hand: after /compact, send “Read .agent/handoff.md before continuing.” Codex CLI 0.157.1 also has PreCompact and PostCompact hook events, which run only after you trust them in /hooks; hooks as deterministic guardrails covers the Codex hook format. In Cursor, start the next chat by pointing it at the handoff file.

5. Clear when the task changes. Start the next outcome with /clear (Claude Code), /new (Codex) or a new chat (Cursor), and a first prompt of: “Read .agent/handoff.md and continue from Next step.”

How do you prove the agent still holds your constraints after a reset?

You should not have to re-read the transcript to know whether compaction dropped something. Use checks whose result you can read in seconds:

• Restate-and-diff. Right after a compaction or a new session, ask: “List the acceptance criteria and the rejected approaches you are working under, verbatim.” Compare the answer with the ## Goal and acceptance criteria and ## Decisions sections of the handoff file. Any missing or reworded item means the context was lost; point the agent at the file before it writes more code.
• Tests as the oracle, not the summary. The acceptance criteria in the handoff file should map to tests that fail before the change. Whether the agent “remembers” is then irrelevant: the test run says whether the behavior exists. See how strong your oracle is for making those tests worth trusting.
• The diff against the “Done” list. git diff --stat should touch the files the handoff note lists and nothing else. An unlisted file is a scope leak and a typical sign that the agent lost its instructions.
• The meter in the review. For long or unattended runs, record the context usage and the number of compactions next to the result. A task that compacted repeatedly deserves a closer review of its decisions, not just its green tests.

The developer who ran the session signs off on the restate-and-diff check; the reviewer signs off on tests and diff scope, as they would for any change.

When the context window works against you

The agent ignores a rule it followed an hour ago. The rule was in the conversation or in a path-scoped rule that compaction summarized away. Recovery: put the rule in the project-root CLAUDE.md or AGENTS.md, or in the handoff file re-injected by the compaction hook, then ask the agent to restate its constraints before continuing.

Compaction keeps firing and each summary is worse. The window is full of tool output, not decisions. Recovery: write the handoff note, /clear or /new, and restart from the file. Filter noisy commands (run one test file, not the suite; pipe build logs through tail) so the new session does not refill with logs.

The agent reads 20 files to answer a narrow question. Broad exploration in the main session. Recovery: interrupt, name the entry point and the files yourself, or send the question to a subagent that returns a summary.

/context shows the window half full before you type. Fixed overhead: a long CLAUDE.md, many MCP servers, many skills. Recovery: run the ablation protocol for context files, and remove MCP servers the project does not use.

Claude Code compacts far too early or too late on a gateway model. Claude Code assumes a window for model IDs it does not recognise, such as an LLM gateway alias. Recovery: for a gateway alias Claude Code does not recognise (and that has no [1m] suffix), set CLAUDE_CODE_MAX_CONTEXT_TOKENS to the model’s real window. For an unrecognised alias that contains [1m], also set CLAUDE_CODE_DISABLE_1M_CONTEXT=1. For an ID Claude Code recognises, the variable takes effect only together with DISABLE_COMPACT, which turns off all compaction, so prefer /autocompact there: if a gateway stops at 200K, run /autocompact 200k (Claude Code model-config docs and 2.1.286 changelog, checked 2026-09-26).

You raised the Codex window and the bill rose with it. Every turn resends the whole window, so a 600K session costs far more per turn than a 150K one, and some providers price long-context input higher. Recovery: keep the default window for routine work and raise it only for a task that needs it; see context cost optimization.

Caution

Disabling auto-compaction (DISABLE_AUTO_COMPACT=1 in Claude Code) does not give the model more room. When the conversation exceeds the window, Claude Code reports that it is over the token limit and you have to compact or clear anyway. Use it only when you compact manually at every phase boundary.

Where to go next with context management

Start with the context management overview if you have not set up CLAUDE.md or AGENTS.md yet. Then:

Pruning CLAUDE.md and AGENTS.md Cut the fixed overhead every turn pays for, and prove each line earns its place.

Long-term context retention Keep decisions and progress across sessions with files, memory and handoffs.

Code search and indexing Make the agent find the right code with fewer, cheaper reads.

Context cost optimization Turn context usage into a number you can budget and reduce.