Claude Code Context: /compact, /clear and CLAUDE.md Explained

Every Claude Code session runs inside a fixed-size context window. Your prompts, the files Claude reads, command output and its own replies all count towards it. When it fills up, quality drops: Claude forgets earlier decisions, repeats work and starts to contradict itself. Managing Claude Code context is the single biggest habit that separates a smooth session from a frustrating one.

What fills the context window

• Every message you send and every reply Claude writes.
• File contents Claude reads, including large files it only needed a few lines from.
• Tool output such as test runs, build logs and git diff results.
• Your CLAUDE.md files and any other instructions loaded at the start of the session.
• MCP tool definitions, which can be surprisingly large if you have many servers connected.

Noisy tool output is usually the worst offender. One failing test run that prints 2,000 lines can cost more context than twenty normal messages.

See where it is going with /context

Run /context to see a breakdown of how much of the window is in use and what is using it. If a single MCP server or a pasted log is taking a big share, you know exactly what to trim. Run /help to confirm which commands your installed version supports, because slash commands are added and renamed between releases.

/compact: summarise and keep going

/compact replaces the conversation so far with a summary, freeing space while keeping the thread of the work. Claude Code can also compact automatically when the window is nearly full, but doing it yourself at a natural break gives better results. You can steer the summary:

/compact Focus on the auth refactor, the failing tests in tests/auth, and the decision to keep session cookies

Without guidance the summary decides for itself what mattered, and details you cared about can be lost. Be specific about decisions, file names and open problems.

/clear: start fresh on purpose

/clear empties the conversation entirely. Use it whenever you switch to an unrelated task. Carrying a finished bug fix into a new feature just adds noise, and the old context can quietly bias Claude’s choices. Your CLAUDE.md is read again at the start of the next turn, so the standing instructions survive a clear.

If you want to come back to an earlier conversation later, claude --continue resumes the most recent session and claude --resume lets you pick one.

Put lasting instructions in CLAUDE.md

Anything you would otherwise repeat in every session belongs in CLAUDE.md at the root of your project: build and test commands, code style rules, folder layout and things Claude must never do. Run /init to generate a starting file, and use /memory to open and edit the memory files that are loaded.

Keep it short. Because the file is loaded every time, a bloated CLAUDE.md permanently eats context and dilutes the rules that matter. A good test: if a line would not change what Claude does, delete it.

# Project notes
- Run tests with: npm run test -- --run
- Use TypeScript strict mode, no any
- API routes live in src/server/routes
- Never edit files under generated/

Habits that keep context healthy

1. Start each distinct task with /clear.
2. Ask Claude to write a plan or notes to a file before you compact, so the important decisions survive in the repo and not only in a summary.
3. Point Claude at specific files and line ranges instead of letting it read whole directories.
4. Pipe noisy commands through tail or grep so only the useful lines come back.
5. Hand large searches and reviews to a subagent. Subagents work in their own context and return only a summary.
6. Disconnect MCP servers you are not using in the current session.

Signs you should compact or clear now

• Claude asks about something you already settled.
• It re-reads files it has already seen.
• Replies get vaguer, or it undoes a change you agreed earlier.
• /context shows the window close to full.

Treat context like working memory: small, relevant and tidied regularly. A five-second /compact or /clear at the right moment is far cheaper than a long session that has quietly gone off the rails.