Claude Code Context Window: When to Compact, Clear or Split

Claude Code's context window is the working memory for your current session. It holds your conversation, every file read, MCP tool definitions, custom agent configs, memory files, and the full history of tool calls, as the Claude Code context window documentation describes. When it gets full, you have three levers: /compact , /clear, or start a new session with a structured handoff. Which one you reach for changes the quality of everything that follows.

Choose Compact, Clear, or a New Session

Three commands, three different outcomes. Understanding the difference is the whole game.

`/compact ` replaces the conversation history with a condensed summary and keeps the session running. The context shrinks, the session continues, and Claude retains some historical awareness. You can steer what it keeps: /compact focus on the auth bug fix tells the model what matters instead of letting it guess. The official context window reference confirms you can pass instructions directly to the compact pass.

`/clear ` is a hard reset. The entire conversation is deleted. No history, no in-memory file context, no carry-over. As Damian Galarza's context window breakdown puts it, using /clear without first persisting your plan means you start from scratch. That's fine, sometimes intentional.

Starting a new session with a handoff document gives you a clean slate plus continuity. More on structuring that handoff below.

The rough decision tree:

1. Same task, more space needed: use /compact with a focus instruction.
2. Switching to unrelated work: use /clear.
3. Task too large for one session or quality already degrading: create a handoff and start fresh.

One thing to flag: /autocompact runs automatically as you approach the limit. You can set how full the window gets before it fires, for example /autocompact 500k , but the automatic pass makes its own decisions about what to keep. That's fine for short sessions. For anything architectural, you want to run /compact manually before the automatic pass takes over.

See What Consumes Context

Before you manage context, you need to see it. Run /context and you get a breakdown: total context size, the categories consuming the most tokens, and a visual bar showing the split. Claude Code 101 from the official academy walks through this output. The main categories are conversation history, file contents loaded into the session, tool call history, and any memory or agent config files.

Most developers are surprised by the tool call history. Long back-and-forth debugging sessions pile up fast. A dozen file reads, each with full output, compounds quickly. That's usually the first thing to target.

What gets preserved through a compact pass

According to the official docs, startup content reloads automatically after a compact. What you need to watch is nuance in the conversation itself: specific architectural decisions, reasons behind a refactor, why you rejected a particular approach. Those survive a focused compact. They often do not survive the automatic pass, which doesn't know what you care about.

Scope Repository Reads and Tool Output

How you read files into the session matters as much as when you compact. Reading entire directories or large files when you only need a function or two is one of the fastest ways to burn context.

A few habits that help:

• Ask Claude to read only the specific file and line range you need, not the whole module.
• When you need to research a large codebase area, delegate to a subagent. The file contents stay in the subagent's context, not yours. You only get the result. The official context window docs call this out explicitly: "Delegate large reads: send research to a subagent so the file contents stay in its context window, not yours."
• Avoid re-reading files you've already discussed unless something changed. Claude already has that content in the conversation.
• Be specific with grep and search tool calls. Broad searches return broad output.

For anyone building multi-agent workflows on top of Claude Code, the Claude Code subagents guide covers how to structure those delegations. And if you're working at the SDK level, the Claude Agent SDK guide goes deeper on context boundaries between agents.

If you're spending more time fighting context than writing code, it may be worth talking to someone who does this full-time. Seahawk's Claude Code development team can help set up the right project structure from the start.

Preserve Decisions When Compacting

This is the step most developers skip. Right before you compact or clear, ask Claude for a summary:

"Before we compact, give me a bullet list of the key decisions we made, anything we explicitly rejected and why, and the current state of the work."

Copy that into your CLAUDE.md or a scratch note. When you resume, paste it in as initial context. MindStudio's guide on the `/compact ` command describes this as the difference between controlled compression and chaotic compression: when you run /compact manually, you choose what gets preserved; when the automatic pass fires, the model decides, and it often keeps mundane output over architectural reasoning.

The other lever is your CLAUDE.md itself. Architectural decisions, non-obvious component relationships, things Claude should never do in this codebase: these belong there permanently, not just in conversation. Every new session loads CLAUDE.md automatically, so it's the one place where context truly persists across sessions.

When not to compact

• Mid-debugging, when specific error messages and stack traces are still relevant.
• During a refactor where file-level detail is actively being used.
• Right before integration work that depends on context from the component you just built.

Claudefast's context management guide summarises this well: compact at natural breakpoints between phases of work, not in the middle of a phase.

Split Large Tasks Without Losing the Handoff

Some tasks are genuinely too large for one session. That's not a failure, it's just how large codebases work. The answer is a structured handoff document created before the session ends, not after quality has already dropped.

A useful handoff document covers:

1. What was completed (with commit references or file paths).
2. What is in progress and what state it's in.
3. Decisions made and why (especially anything non-obvious).
4. What comes next, with enough detail that a fresh session can pick it up without re-reading everything.
5. Any open questions or blockers.

One practitioner on LinkedIn described this as the core of a session handoff system: at a set context usage level, the session creates a handoff document with what was done, commit references, and current state. The new session opens with that document as its first message. The LinkedIn post by JD Fiscus on compact vs clear describes a TASK > COMMIT > CLEAR > RECAP > RESCAN loop for keeping tasks focused, which works well for iterative feature work.

The workflow, concretely:

1. Complete a logical unit of work and commit.
2. Ask Claude to produce a handoff summary covering the five points above.
3. Copy the summary to a file in your repo or to CLAUDE.md.
4. Run /clear or start a new session.
5. Open the new session with the handoff document as context.

This way you're never starting from zero and you're never dragging a cluttered session history into work that needs a clear head.

Model-Specific Limits and Troubleshooting

Context window sizes vary by model. The Damian Galarza post notes Claude Sonnet 4.5 has a context window of around 200,000 tokens as a reference point. Other Claude models have their own limits; check the official model documentation for current figures rather than relying on community numbers that may be outdated.

What to watch for:

• Repetition. Claude starts asking questions you've already answered, or contradicts an earlier decision. That's a signal the relevant context has been pushed out or summarised poorly.
• Ignored instructions. If Claude stops following project conventions it was handling correctly earlier, the CLAUDE.md content may have been crowded out. Run /context to check.
• Slow, expensive responses. A large context costs tokens on every message. If costs are climbing, /context will show you why.

One thing worth noting: claims about universal compaction thresholds (a specific percentage of fill at which quality always drops) are not supported by the official documentation. The right time to compact is task-dependent. The rough heuristic from several practitioners is to act at a natural phase boundary, before you see degradation, not after. But your mileage will vary by task type, model, and how much of your context is dense code versus conversation.

FAQ

Does `/compact` cost tokens?

Yes. The compaction pass itself is a model call and uses tokens. Running it manually at a phase boundary usually costs less than letting the automatic pass fire at a high utilisation level, because the summary it produces is cleaner and you spend fewer tokens on the messages that follow.

Will `/clear` affect my `CLAUDE.md`?

No. CLAUDE.md is a file on disk. /clear removes the in-session conversation and memory only. Your CLAUDE.md reloads automatically the next time Claude Code reads your project directory.

Can I compact just part of the conversation?

Yes. Run /rewind, select a message, and choose "Summarize from here" or "Summarize up to here." The official context window docs describe what each option keeps. This is useful when a specific debugging thread is cluttering the context but the earlier conversation still matters.

Do same-repository worktrees share context?

They share machine-local auto memory, per the official memory documentation. They do not share session context. Each worktree session has its own context window.

What happens to MCP tool definitions after a compact?

The official docs indicate that startup content, including MCP tool definitions, reloads automatically after a compact pass. You should not need to re-register tools manually, but it is worth running /context after a compact on a complex session to confirm the breakdown looks correct.

The sharpest caveat in all of this: by the time you notice quality degrading, your compact summary is likely to include confused outputs alongside the good ones. Compact at the end of a clean phase, not at the start of a messy one.