Context Management

Every Claude Code session has a finite context window. How you manage that window — when you compact, how you structure tasks, how you name and resume sessions — determines whether Claude stays sharp for the full duration of your work or quietly degrades into unreliable output well before the limit is reached.

The “Dumb Zone” Problem

The “dumb zone” is what happens when Claude’s context window fills past a certain threshold but has not yet triggered an automatic compaction. In this range, Claude has not lost access to earlier content yet, but the sheer volume of accumulated context forces it to make tradeoffs. Constraints established early get deprioritized. Patterns that were clear in a fresh session become blurry. Output quality degrades noticeably before the window technically overflows.

The dangerous part is that this happens silently. Claude does not announce “I’m getting confused.” You only notice when something that should have been straightforward comes back wrong — a file it was explicitly told not to touch gets modified, an architectural decision it confirmed ten prompts ago gets reversed.

Note: The dumb zone typically begins around 60–70% context usage. The safe operating threshold is 50%.

The 50% Rule

Manually /compact at a maximum of 50% context usage. Do not wait for Claude to auto-compact.

# Check current context usage
/context

# Compact immediately (basic)
/compact

# Compact with a focus instruction (recommended)
/compact focus on the authentication refactor, ignore the earlier debugging session

Auto-compaction happens at 95%+ usage — deep in the dumb zone. By the time it triggers, quality has already been compromised for a significant stretch of work. The 50% rule means you compact while Claude still has clear recall of everything important.

Why Focus Instructions Matter

When you run /compact without a focus instruction, Claude summarizes the entire conversation as evenly as it can. This preserves noise alongside signal — all the exploratory back-and-forth, the approaches you abandoned, the debugging tangents that led nowhere.

A focus instruction tells Claude what to compress carefully and what to discard:

# Preserve the architecture decision, drop the setup noise
/compact focus on the API design decisions and schema we agreed on, ignore the environment setup issues

# Preserve the bug investigation findings, drop the failed attempts
/compact focus on the root cause we identified in auth.ts, ignore the earlier failed hypotheses

# Preserve implementation progress, drop the exploratory discussion
/compact focus on what has been implemented so far and the remaining TODOs

The compacted summary Claude carries forward is dramatically cleaner. The working session after a focused compact feels like a fresh start with the right context already loaded.

`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`

For complex tasks where you want an extra safety margin, set a custom compaction threshold:

# In your shell profile (~/.bashrc, ~/.zshrc)
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=40

# Or in .env.local for project-specific override
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=40

This triggers auto-compaction at 40% instead of the default 95%. Combined with the manual 50% rule, it gives you two layers of protection: you compact manually at 50%, and if you miss it, auto-compaction fires at 40% as a floor.

Use lower thresholds (30–40%) for tasks involving:

Long-running refactors spanning many files
Complex debugging sessions with many hypothesis-test cycles
Architectural planning with lots of exploratory discussion

Use the default (or omit the override) for:

Short focused tasks
Single-file edits
Quick question-and-answer sessions

Monitoring Context Usage

The `/context` Command

/context

Displays a colored grid showing context window usage broken into segments. Each cell represents a portion of your context window — green for recent content Claude holds clearly, yellow for older content it is summarizing, red for content at compaction risk.

Desktop App Status Bar

In Claude Code Desktop, the bottom status bar shows a live context indicator. Watch for it turning from green to yellow — that is your signal to consider a /compact.

Session Naming and Labeling

When running multiple parallel Claude sessions, you need a way to distinguish them in session lists.

# Start a named session
claude --label "feat-auth"
claude --label "debug-payment-flow"
claude --label "refactor-data-layer"

The label appears in the session list when you run claude sessions. Without labels, sessions are identified only by ID and timestamp — nearly impossible to navigate when you have five running simultaneously.

Tip: Use the same label convention as your git branches. If you are on feat/auth-refactor, label the session feat-auth-refactor. The mental model aligns.

Session Resuming

# List available sessions
claude sessions

# Resume a specific session by ID
claude --resume session-abc123

# Resume the most recently active session
claude --resume last

Resuming picks up exactly where the session left off — conversation history, file context, tool results. You do not need to re-explain what you were working on or re-establish constraints. This is the correct way to continue work across terminal restarts, machine sleep/wake, or switching between tasks.

When to Resume vs. Start Fresh

Scenario	Recommendation
Continuing same task after a break	`--resume`
Starting a related but distinct task	New session, reference the old one
Context is clearly stale or confused	New session, manually re-state key constraints
You are past 50% on a resumable session	`--resume` then immediately `/compact`

Session Forking

For experimental work where you want to preserve a known-good state before trying something risky, use /branch to fork the current session. The fork starts from the same context snapshot but evolves independently.

See Branch: Fork a Session for full documentation.

Context Lifecycle

flowchart TD START([Fresh Session]) --> FILL["Context fills\n(work progresses)"] FILL --> CHECK{"/context check\nAt 50%?"} CHECK -- No --> FILL CHECK -- Yes --> COMPACT["/compact with focus"] COMPACT --> FRESH["Compacted session\n(clean context)"] FRESH --> FILL2["Context fills again"] FILL2 --> CHECK2{At 50% again?} CHECK2 -- No --> FILL2 CHECK2 -- Yes --> COMPACT2["/compact with focus"] COMPACT2 --> DONE([Task Complete]) style START fill:#1e293b,color:#86efac,stroke:#334155 style FILL fill:#1e293b,color:#7dd3fc,stroke:#334155 style CHECK fill:#1e293b,color:#fcd34d,stroke:#334155 style COMPACT fill:#1e293b,color:#7dd3fc,stroke:#334155 style FRESH fill:#1e293b,color:#86efac,stroke:#334155 style FILL2 fill:#1e293b,color:#7dd3fc,stroke:#334155 style CHECK2 fill:#1e293b,color:#fcd34d,stroke:#334155 style COMPACT2 fill:#1e293b,color:#7dd3fc,stroke:#334155 style DONE fill:#1e293b,color:#86efac,stroke:#334155

Subtask Sizing

Design each Claude subtask to fit within 50% of the context window. This is not a soft guideline — it is a hard architectural constraint for reliable multi-step work.

Practical implications:

One goal per session. Do not ask Claude to refactor the auth module and add test coverage and update the docs in one session. Three tasks, three sessions.
Scope file context deliberately. If you are working on src/api/auth.ts, do not load the entire src/ directory. Load the relevant files only.
Break long tasks at natural checkpoints. After completing a logical unit of work (a module, a feature slice), commit the work, compact, and continue in the refreshed session.

Multi-Session Workflow: Orchestrator + Workers

For large tasks that genuinely require many steps, use the orchestrator + worker pattern:

Orchestrator session
  ├── Holds the overall plan and progress state
  ├── Assigns focused subtasks to worker sessions
  └── Reviews and integrates worker output

Worker session A (--label "worker-auth")
  └── Executes one focused subtask, commits output

Worker session B (--label "worker-tests")
  └── Executes one focused subtask, commits output

The orchestrator stays context-light because it manages coordination, not implementation. Workers start fresh for each subtask, so they never accumulate stale context. This pattern scales to arbitrarily complex tasks while keeping every individual session within the 50% threshold.

Context Anti-Patterns

Loading the entire codebase at session start. If you reference too many files upfront, the context fills before you have done anything useful. Load files as needed, not preemptively.

Asking for too many things in one prompt. Multi-part requests generate multi-part responses and back-and-forth that compounds context usage fast. One clear request per turn.

Forgetting to compact after major milestones. Finishing a module or a feature is a natural compaction point. Do not carry all that implementation detail into the next phase — compact with a summary of what was completed.

Relying on auto-compaction. By the time auto-compact fires, you have already spent time in the dumb zone. Do not use it as your primary compaction strategy.

Resuming stale sessions without checking context. If you resume a session that was near the 50% mark when you left it, run /context immediately. You may be stepping back into the dumb zone.