Library
Claude Code Documentation (June 2026) · 7 of 15
Claude Code Documentation (June 2026)
ai CRITICAL

Context & Session Management

Claude Code Documentation (June 2026) Anthropic
context-window claude-md sessions subagents hooks skills

Key Principle

The context window is the scarce resource and almost every best practice exists to protect it. It holds the entire conversation — every message, file read, and command output — and fills fast (a single debugging session can burn tens of thousands of tokens). As it fills, Claude forgets earlier instructions and makes more mistakes: "It is the most important resource to manage." (Section: Manage the context window). Track usage continuously with a custom status line.

Why This Matters

Specific prompts, @-references, CLI tools over MCP, skills over CLAUDE.md, and subagents all exist to put the right tokens in and keep noise out (chunk 014 through-line). Most common failures are ways the window gets wasted; the fix recovers it (p. 1, Common mistakes).

Good Examples

CLAUDE.md is read at the start of every conversation — persistent context Claude can't infer from code. /init generates a starter file by analyzing the project; refine over time. Keep it short — "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" (Section: Write an effective CLAUDE.md). For each line ask: "Would removing this cause Claude to make mistakes?" If not, cut it. Import other files with @path/to/import:

See @README.md for project overview and @package.json for available npm commands.
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

Scopes: ~/.claude/CLAUDE.md (all sessions); ./CLAUDE.md (project, check into git); ./CLAUDE.local.md (personal, .gitignore it); parent dirs auto-load in monorepos.

Subagents run in separate context windows and report back only summaries, keeping the main conversation clean — one of the most powerful tools because context is the constraint (Section: Use subagents for investigation). Define in .claude/agents/ with its own allowed tools:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---

Skills load on demand, holding domain knowledge that would bloat CLAUDE.md if always-on (SKILL.md in .claude/skills/). Use disable-model-invocation: true for side-effecting workflows you want to trigger manually:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

Invoke with /fix-issue 1234. Hooks are deterministic and guarantee the action happens, unlike advisory CLAUDE.md instructions (which Claude may follow) — use them for actions that must happen every time with zero exceptions, e.g. lint on every edit (Section: Set up hooks). Configure in .claude/settings.json; browse with /hooks.

Counterpoints

Common context-pollution mistakes and their fixes (p. 1):

  • Kitchen-sink session — unrelated tasks fill context with irrelevant info. Fix: /clear between unrelated tasks.
  • Correcting over and over — failed corrections accumulate as noise. Fix: after two failed corrections, /clear and rewrite the initial prompt with what you learned. "A clean session with a better prompt almost always beats a long session carrying accumulated corrections."
  • Over-specified CLAUDE.md — important rules get lost in the noise. Fix: prune ruthlessly, or convert a rule to a hook (deterministic enforcement costs no tokens or attention). Rule repeatedly violated → file is probably too long.
  • Infinite exploration — an unscoped "investigate" makes Claude read hundreds of files. Fix: scope narrowly, or push exploration into a subagent.
  • Develop intuition — these are starting points, not rules; sometimes let context accumulate (deep in one problem) or stay vague (exploratory task) (p. 1).

CLI tools are the most context-efficient way to reach external services (gh, aws, gcloud, sentry-cli); MCP (claude mcp add) is more capable for stateful/structured integrations but heavier on context — prefer a CLI when one exists (Section: Use CLI tools / Connect MCP servers).

Key Commands & Config

# Session / context management
/clear                      # reset context between unrelated tasks
/compact <instructions>     # e.g. /compact Focus on the API changes
/rewind  (alias /undo)      # rewind menu; also Esc+Esc; restore conv/code/both
                            #   -> Summarize from here / Summarize up to here
/btw                        # quick question; never enters history (overlay)
Esc                         # stop mid-action, context preserved
claude --continue           # resume most recent session
claude --resume             # choose session from a list
/rename                     # name a session; treat like a branch per workstream

# Checkpoints: every prompt creates one; Claude auto-snapshots files before each
# change. Persist across sessions. NOT a git replacement (tracks only Claude's
# changes, not external processes).

# Customization surfaces
/permissions                # allowlist safe tools
claude mcp add              # connect external tools (heavier on context)
.claude/settings.json       # hooks (deterministic)  -- /hooks to browse
.claude/skills/  SKILL.md   # on-demand skills        -- /skill-name to invoke
.claude/agents/             # context-isolated subagents
/plugin                     # browse marketplace (skills+hooks+subagents+MCP)
/init                       # generate starter CLAUDE.md

# Non-interactive scaling
claude -p "your prompt"                      # no session; CI / scripts / hooks
claude -p "..." --output-format json|stream-json
claude -p "..." --allowedTools "Edit,Bash(git commit *)"   # scope unattended runs
claude --permission-mode auto -p "fix all lint errors"     # classifier-gated
@file  @directory/  @path/to/import          # feed context in
cat error.log | claude                       # pipe data in

Rules of Thumb

  • Reset or compact context aggressively to hold performance; /clear frequently between tasks.
  • Customize compaction in CLAUDE.md so critical context survives, e.g. "When compacting, always preserve the full list of modified files and any test commands".
  • If a rule belongs in every session and must be enforced, use a hook; if it's domain knowledge or sometimes-relevant, use a skill; only broadly-applicable context belongs in CLAUDE.md.
  • For large fan-out (for file in ...; claude -p ...), refine the prompt on the first 2–3 files, then run the full set; turn --verbose off in production.

Related References