/compact Command

The `/compact` command is Claude Code's tool for managing a growing conversation without hitting the reset button. It summarizes your entire chat history, code, tool outputs, and dialogue, into a condensed, token-efficient baseline. This summary replaces the sprawling original, allowing Claude to continue the current task with a significantly reduced context load. Think of it as distilling a lengthy meeting transcript into a concise executive summary: key points remain, but conversational filler and verbatim exchanges are gone. This process is inherently lossy; it is a strategic distillation, not perfect recall. You can guide this process: `/compact focus on the authentication bug` or `/compact keep the database schema changes` directs Claude to prioritize specific details, making the summary far more reliable. Claude Code also includes an auto-compaction safety net. When your conversation approaches the context window limit, the system automatically triggers a `/compact`, behaving identically to a manual one. You cannot disable this, so proactive, guided compacting is key. After a `/compact`, persistent elements like your system prompt, project-root CLAUDE.md, auto-memory, and invoked skill bodies are re-injected. However, path-scoped rules and nested CLAUDE.md files are dropped, returning only when a matching file is read again. This distinction is vital for consistent behavior in complex projects.

`/compact` is not `/clear`. This is the most crucial distinction. `/clear` starts a fresh session with an empty window, ending one task and beginning another. `/compact` keeps you in the same task, preserving a summarized history. It is not a fresh start, but a continuation. Therefore, `/compact` should not be your default for task transitions. The Claude Code team, including @trq212, strongly advocates `/clear` for new tasks, arguing `/compact` often carries unnecessary noise. Medium author Mubashar agrees: "default to clear, reach for compact when continuity matters." Second, `/compact` is not a perfect memory. It is lossy. Verbatim conversation, exact tool outputs, and precise wording are crushed into a summary. If you need every detail, `/export` your transcript first. Third, `/compact` is not a universal context solution. It primarily addresses conversation history. If `/context` shows your window is full from MCP server definitions, skill bodies, or file reads, `/compact` will offer minimal relief. For example, if MCPs and skills consume 70% of your window, compacting chat barely helps. Fourth, you cannot turn off auto-compaction. It is a built-in safety mechanism. The discipline is to manage proactively with a guided compact, before the system intervenes blindly. Finally, `/compact` is not a magic bullet for dynamic rules. Path-scoped rules and nested CLAUDE.md files are dropped after a compact, returning only when a matching file is read again. This can subtly alter Claude's behavior without warning.

Imagine you are a senior engineer at Brainy Papers, debugging a complex, intermittent authentication bug. You have been in a Claude Code session for hours, tracing calls and generating test cases. Your conversation history is now a sprawling mess of code, errors, and hypotheses. Claude feels sluggish. Running `/context` shows your conversation history consumes 75% of your 200K token window. This is a classic `/compact` scenario. You cannot `/clear` because you would lose intricate debugging steps and specific error patterns. Instead, you type: `/compact focus on the authentication flow, the specific error messages from the last hour, and the proposed solutions for the JWT token validation`. Claude processes this, summarizing the vast conversation into a concise, focused baseline. The token count drops significantly, perhaps from 150K to 30K. Claude regains responsiveness, and you continue debugging with essential context preserved. This is a guided compact in action. Anthropic's own tool-use cookbook demonstrates auto-compaction cutting input tokens by 58% in a multi-ticket agent run, from 204K down to 82K. An analysis at hyperdev.matsuoka.com reported that proactive compacting around 60% capacity, instead of waiting until 95%, plus better context editing, delivered up to 39% better performance. These real-world results confirm that `/compact`, used intelligently and proactively, saves tokens and maintains performance during long, complex tasks.

Use `/compact` when you are deep into a single, long-running task and need to maintain its historical continuity, but your context window is saturating. This applies to debugging a persistent bug or developing a complex feature over extended periods where the accumulated conversation is directly relevant. Always run `/context` first; if conversation history is the primary token hog, `/compact` is your tool. Crucially, always guide your compact with specific instructions, like `/compact keep the API contract details and test cases for the payment gateway`. A guided summary is far more reliable than a blind one. Proactive compacting is key; do not wait for auto-compaction. Compacting at 60% or 70% capacity gives you control and prevents a panicked, blind summary mid-thought.

Do not use `/compact` when you finish one task and start a new, unrelated one. For instance, after implementing a feature, move to documentation with `/clear`. Dragging feature development history into documentation introduces noise. The Claude Code team's mantra, "STOP COMPACTING, use /clear," and Mubashar's advice, underscore this. Avoid `/compact` if you need verbatim detail, exact tool outputs, or precise wording, as it is lossy. Use `/export` first for an exact record. If `/context` reveals token bloat from non-conversation elements like MCP definitions, skill bodies, or large file reads, `/compact` offers minimal benefit. Address the root cause, perhaps with subagents. Be cautious if your project relies on path-scoped rules or nested CLAUDE.md files; these are dropped after a compact and only re-injected when a matching file is read again, potentially altering Claude's behavior without warning.

`/compact` trades verbatim detail for task continuity, allowing you to sustain complex, long-running work without drowning in an ever-expanding conversation history.