Contents

Claude Code's /compact is not something you press on a timer. The moment to press it is a break in the work — one task finished, the next one about to start. The official documentation says so in as many words: run /compact at a natural breakpoint in the work, such as between tasks, rather than waiting for auto-compaction to trigger in the middle of a task (Claude Code docs, "Prompt caching").

Rules like "press it every 30 minutes" or "press it once context passes 70%" are aiming at the wrong target. The rest of this article works through why, but the short version is this: the cost and the loss of a compaction are decided not by when you pressed it, but by what you threw away and whether the cache was warm.

📌 Where these facts come from: every spec, version number and setting name below was checked on 8 August 2026 against the Claude Code documentation and the release notes (latest at that point: v2.1.226, 8 August 2026). Claude Code moves fast, and the compaction area has gained behaviour even in recent releases (/autocompact requires v2.1.221 or later). Check your own build with claude --version.

1. The short answer — press it at a boundary, not on a timer

Here is the decision table first. It exists to let you decide by situation rather than by the clock.

✅ When to press it

You have finished one task and are about to start a long one. It does not matter that there is context to spare. The point is to pull the automatic run forward on your own terms so that nothing interrupts you mid-task.

🟡 When /clear is the better call

The next job has nothing to do with the last one. If you do not even need the summary, there is no reason to pay for producing one. The docs put it plainly: if you want a fresh start rather than continuity, /clear is free.

🔵 When /rewind is the better call

You want to throw away the whole direction you took. Rewinding truncates back to a point that is already cached, so it is cheaper than a compaction, which has to build a brand new prefix.

❌ When not to press it

The middle of a task. Details you were still going to use get flattened into a summary. Every "just in case" compaction buys you the job of re-reading the same files immediately afterwards.

One question separates those four. Are you still going to need what you are about to throw away? To borrow the documentation's own framing, compaction helps when the context you are dropping is genuinely no longer needed. A fixed schedule is a way of refusing to make that judgement, so sometimes it lands and sometimes it does not — and the times it misses cost more than the times it hits.

2. Compaction runs in three stages — what the docs actually say

Before you can ask whether to press it manually, you need to know about the machinery that runs whether you press anything or not. When context starts filling up, Claude Code does not jump straight to summarising the conversation. The documentation describes it like this.

"Claude Code manages context automatically as you approach the limit: it drops old tool outputs first, then summarizes the conversation if needed. Your requests and important code snippets are preserved, but detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on the conversation history." (How Claude Code works)

So there are stages: (1) old tool outputs are dropped, (2) the conversation is summarised automatically, (3) you press /compact.

1. Dropping tool output

The conversation stays intact and only old tool results fall away. You do nothing. This layer works before summarisation is ever reached.

2. Auto-compaction

When stage 1 is not enough, the conversation itself is replaced by a summary. This is the same processing as a manual /compact; the only difference is when it runs.

3. Manual /compact

Its one and only real job is to pull stage 2 forward to a moment that suits you. On top of that, you can tell it what to keep — the other difference from stage 2.

This is the heart of the answer. A manual /compact brings forward something that would have happened anyway. It is not a lever that saves extra context the more often you pull it. It is worth pressing only when choosing the timing yourself is worth something.

⚠️ A note on terminology. Several write-ups call stage 1 "micro-compaction", but as of 8 August 2026 the official documentation does not use that name. What the docs give is a description of the behaviour — old tool outputs are dropped first. If you search for the term and find nothing official, this is why.

3. What survives, and what disappears

What happens to your rules during a compaction depends entirely on how they were loaded. The documentation publishes a per-mechanism list, so here it is, organised.

Mechanism After compaction What it means in practice
System prompt and output style Unchanged They are not part of the conversation history
CLAUDE.md at the project root and unscoped rules Re-injected from disk The safest place to put things. It is also where your edits finally take effect (see section 8)
Auto memory Re-injected from disk It is designed to persist across sessions, so surviving a compaction is the least it can do
Rules carrying paths: Lost (until a matching file is read again) To keep them, drop the paths: key or move the rule into the root CLAUDE.md
Nested CLAUDE.md in a subdirectory Lost (until a file in that directory is read again) Same as above, and the easiest omission to miss
Bodies of skills you invoked Re-injected, but capped 5,000 tokens per skill and 25,000 in total, with the oldest dropped first
Hooks Not applicable They run as code, not as context

Three practical conclusions fall out of that table.

First, if you expect to be compacted, put the rules you cannot afford to lose in the CLAUDE.md at the project root. That is the one point the documentation keeps repeating. Rules with paths: and nested CLAUDE.md files buy convenience at the price of falling out on every compaction — and nothing on screen tells you they went.

Second, the top of a skill file is what matters. Truncation on re-injection keeps the start of the file, so the important instructions in a SKILL.md belong at the top. On top of that, the documentation's context notes say that the list of skills loaded at session start is not re-injected after a /compact; only the skills you actually invoked are retained.

Third, nothing announces what was lost. Which is exactly why the principle holds: if losing something would hurt, keep it in a file rather than in the conversation.

4. The cost is not decided by how big your context is

Assuming that "a bigger context makes /compact more expensive" is natural, and only half right. What actually drives the price is whether the prompt cache is warm. Here is the documentation's explanation.

"To produce the summary, Claude Code sends a separate request with the same system prompt, tools and history, plus a summarisation instruction at the end. While the cache is warm, that request reads your prefix from cache, so it costs far less than the size of the context would suggest, and most of the time goes into generating the summary. [...] After a break longer than the cache lifetime there is no cache left to read, so the summarisation request reprocesses the entire history as uncached input. That is why /compact is at its most expensive when you resume an old session." (Prompt caching)

That single paragraph is the strongest argument against running compaction on a schedule.

Pressed mid-session (cache warm)

The prefix is read from cache. What you feel is only the time spent writing the summary. One compaction here is cheap.

Pressed after a break (cache cold)

The whole history is reprocessed before anything is summarised. The single most expensive moment for the same command. "Let me tidy up first thing in the morning" can be the worst possible move.

The turn right after you press it

The cache is rebuilt from a short summary, so this part is not heavy. The impression that "things get slow after a compaction" usually comes from the two cases above, not from here.

Cache lifetime depends on how you authenticate. On a Claude subscription a one-hour TTL is requested automatically; through an API key or a cloud provider the default is five minutes (ENABLE_PROMPT_CACHING_1H=1 raises it to an hour). Which means "back from lunch, let me run /compact first" is almost guaranteed to be a cold run on an API key.

The fact that /compact is itself a large request is underlined in the cost documentation too: "/compact reads the conversation it is summarising, so compacting a large context is itself a large request. If you want a fresh start rather than continuity, /clear is free." (Manage costs effectively). Seen through the lens of token saving as well, there are plenty of moments where /clear beats a /compact pressed out of habit.

5. /compact vs /clear vs /rewind vs /recap

/compact is not the only way to lighten your context. Confuse commands that exist for different purposes and you end up paying for the expensive one.

Command Conversation history Cache When to choose it
/compact [instruction] Replaced by a summary The conversation layer is invalidated You are continuing, but you no longer need the details of the history
/clear [name] Emptied Rebuilt (no summarisation cost at all) The next job is unrelated. Give it a name and /resume brings it back
/rewind Truncated back to an earlier point Hits the older cache You want the whole direction gone. Code can be rolled back with it
/recap Untouched (it only shows a summary) Kept as is You just want to read "where we are so far"
/context [all] Untouched Kept Measure before you press anything. A colour-coded view of what is taking up room

/recap is worth remembering. Plenty of people press /compact because "this conversation is getting long, I would like it summarised" — and for that purpose there is no need to destroy the history. Per the docs, /recap merely appends a summary as command output, so the cached prefix stays intact.

The nature of /rewind matters just as much. The documentation explains that rewinding returns you to the same content that was cached at that point, so the next request hits the older cache. When you have gone in the wrong direction, the right answer is /rewind, not /compact — compaction builds a new prefix, whereas rewinding just goes back to one that already exists. Checkpointing and rewind have their own article.

6. You can move the auto-compaction window yourself

Before agonising over whether to press it by hand, it is worth knowing that you can move the point where the automatic run fires. From v2.1.221 onwards, the /autocompact command lets you specify how full the context has to get before auto-compaction kicks in.

Set the window to 500K tokens (saved to user settings, so it applies to later sessions too)

/autocompact 500k

Return to the model-appropriate default

/autocompact auto

The accepted range is 100K to 1M tokens. You can write a plain number such as 200000, a suffixed value such as 500k or 1M, or a bare number between 100 and 1000 such as 200 (read as thousands). The setting can arrive from four places, and the precedence is fixed.

1. Environment variable (highest)

CLAUDE_CODE_AUTO_COMPACT_WINDOW. While it is set, it overrides the command, the flag and the settings file

2. Launch flag

claude --autocompact 500k. Applies to that launch only and does not change your saved settings

3. The command

/autocompact. Writes to autoCompactWindow in your user settings

4. Settings file

autoCompactWindow. If your organisation has a managed setting above it, that one wins

⚠️ The environment variable is the one with a different format. The documentation states explicitly that CLAUDE_CODE_AUTO_COMPACT_WINDOW accepts a plain integer only, and that a value like 500k is read as 500 and clamped to the 100K minimum. Write it the way you write the command and you have asked for a thousandth of what you meant, then been clamped up into compacting far more often.

There is a second warning in the same place. The status line's used_percentage always measures against the model's full context window, so once you set this variable that percentage no longer tells you when compaction will fire. This is precisely where a "watch the percentage and press it manually" workflow falls apart.

The default, when you set no window at all, is documented too. With nothing configured, compaction happens when the model's context limit is reached, with exceptions: cloud sessions compact early as they approach the limit, Sonnet 4.6 and Opus 4.6 without extended context compact at the 200K boundary, Opus 4.8 and Opus 5 running with 200K context on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry behave the same way, and Sonnet 5 fires at that model's own default threshold.

You can also turn auto-compaction off entirely, via the autoCompactEnabled setting (default true, shown as "Auto-compact" in /config) or the DISABLE_AUTO_COMPACT environment variable. It is not recommended. Switching it off does not shrink anything; the context simply runs into the ceiling and you trade compaction for the "Prompt is too long" error. Auto-compaction is a feature protecting you, not one getting in your way.

7. Three situations where a fixed schedule backfires

With those specifics in hand, it becomes clear where "just press it regularly" loses money.

1. Pressing it mid-task

Details you were still going to use get flattened into the summary. On top of that, paths: rules and nested CLAUDE.md files fall out, so the work immediately afterwards starts quietly missing your rules. It is the kind of degradation whose cause is hard to see.

2. Pressing it first thing after a break

The cache has expired, so the entire history is reprocessed before it is summarised. That is the most expensive moment for the same /compact — and the good intention of "let me tidy up before I start" walks straight into it.

3. Pressing it in a short session

With no history worth summarising you just get Not enough messages to compact. It also happens when one enormous paste filled the context — and there the right answer is /clear, not a summary.

Turn that around and you get the rule: the single highest-value manual compaction is the one immediately before you start a long piece of work. Pressing it there lowers the odds of auto-compaction interrupting you halfway through. The value is in the timing, not the count.

8. In practice — what you do before pressing it matters more

What genuinely moves the needle with /compact is not how you press it but what you commit to files before you do. As the table in section 3 shows, the CLAUDE.md at the project root and your auto memory are re-injected from disk. Anything written there survives any number of compactions.

There is one more property that gets overlooked. Editing CLAUDE.md during a session does not take effect there and then. The documentation puts it as "edits do not invalidate the cache, but they also do not take effect. The new content is loaded at the next /clear, /compact, or restart." Read the other way round, that means /compact is also the operation that makes rules you decided mid-session actually apply.

A checklist for before you press it

  • Have you written the rules and decisions from this session into a file? (Anything that exists only in the conversation gets diluted by the summary)
  • Have you told it what to keep? You can hand over a focus, as in /compact keep the auth fix plan and the test results
  • Is the next job really a continuation? If it is unrelated, /clear is cheaper
  • Is the cache warm right now? (Avoid the moment straight after a long break)
  • When in doubt, run /context and measure what is actually taking up room

And here is the point that people considering manual compaction miss most often. The habit of "I press it myself, pre-emptively, because I am afraid of being compacted behind my back and losing the thread" is common enough. But the documentation says this immediately after explaining auto-compaction: to control what is preserved through compaction, add a "Compact Instructions" section to your CLAUDE.md, or run /compact with a focus (How Claude Code works).

In other words, specifying a focus is not a privilege of pressing it yourself. Put it in CLAUDE.md and it also applies to the compaction that runs while you are away from your desk. If the point of your pre-emptive manual routine is to decide how the context gets trimmed, this is the version that actually works — the manual routine only ever helps while you are watching.

Writing it is not difficult. The documentation's own example looks like this.

Default compact instructions placed in CLAUDE.md (example from the official docs)

# Compact instructions

When you are using compact, please focus on test output and code changes

For what it is worth, here is how this site runs it. The CLAUDE.md in this blog's repository has carried two rules for a long time: "suggest /compact to the user once the context gets long" and "before running /compact, save anything that should become a rule — feedback, decisions on approach — to memory". This very article was written in a session that went through a compaction. In daily use it is not the first rule that earns its keep, it is the second. Getting the things worth keeping into files beforehand works far more reliably than trying hard to shape the summary.

One more thing worth adding: /compact is not the only way to reduce context. The official cost guidance recommends delegating work with heavy output — running tests, fetching documentation, processing logs — to subagents. A subagent has its own context window and returns only a summary, so the main context never swells in the first place. Arranging not to need compaction beats compacting well.

9. Two messages you may run into

Two messages you can hit in practice are less than self-explanatory.

Message What it means What to do
Not enough messages to compact. There is no conversation worth summarising. It also happens when a single enormous paste filled the context Start over with /clear
Autocompact is thrashing: the context refilled to the limit... Compaction succeeded, but a huge file or tool output refilled the context immediately afterwards, several times over. It has stopped to avoid an endless loop The four steps on the right (the docs' recommended order)

The recovery for the second is spelled out in order in the documentation. (1) Read huge files in pieces, by line range or by function. (2) Compact with an instruction naming the output you want dropped (for example /compact keep only the plan and the diff). (3) Move that work to a subagent so it runs in a separate context window. (4) If the earlier conversation is no longer needed, /clear. The telling part is that step 1 comes first: the documentation is effectively saying this is not a compaction problem, it is a reading problem.

Summary

You do not need to run /compact manually on a schedule. Auto-compaction runs whether you do or not, and it is the same processing. Pressing it yourself buys exactly two things — choosing the timing, and specifying what to keep — and both of them pay off in one place: between tasks.

On cost, a schedule loses as well. The price of a compaction is set by whether the cache is warm, so the post-break "let me tidy up before I start" is the most expensive version of it. If a fresh start will do, /clear is free; if you are changing direction, /rewind is cheaper because it returns to an existing cache; and if you only want to read a summary, /recap leaves the history alone. Picking the right one of the four beats pressing the same one more often.

The most practical conclusion, though, lies outside the question of how to press it. Whatever you cannot afford to lose belongs in a file, not in the conversation. The CLAUDE.md at the project root and your auto memory are re-injected from disk, while paths: rules and nested CLAUDE.md files drop out silently. Knowing that asymmetry is what separates a long session that holds up from one that quietly degrades.

FAQ

Q1. So how many minutes apart should I press /compact?

It should not be decided by time at all. The only recommended moment is right after one task finishes and before you start the next long one. The documentation says "at a natural breakpoint in the work, such as between tasks" and gives no time or percentage threshold.

Q2. Is it fine to leave everything to auto-compaction?

Automatic and manual are the same processing; only the timing differs. The catch is that the automatic one can interrupt you mid-task. Pressing it once by hand before a long stretch of work lowers the odds of that interruption. And you can give the automatic one instructions too — write them in CLAUDE.md under a # Compact instructions heading and they apply to a compaction that runs while you are away from your desk (see section 8).

Q2-2. After it compacted on its own, my instructions seem to stop landing

You are not imagining it. The documentation states that "detailed instructions from early in the conversation may be lost". On top of that, paths: rules and nested CLAUDE.md files drop out until the matching file is read again, and invoked skills are discarded oldest-first once they exceed 25,000 tokens in total. It is less that content disappears and more that the rules being followed quietly thin out, so the work carries on while only the accuracy falls. Three countermeasures: (1) move the rules you want to persist into the root CLAUDE.md, where they are re-injected; (2) name what to keep with # Compact instructions; (3) use /autocompact to fire earlier so compaction is not happening right at the ceiling.

Q3. Should I use /compact or /clear?

/compact if the next job continues the last one, /clear if it does not. The cost documentation states outright that "if you want a fresh start rather than continuity, /clear is free". Pass /clear a name and you can come back to the session from the /resume list, so there is nothing to be afraid of losing.

Q4. Does compaction wipe my CLAUDE.md rules?

The CLAUDE.md at the project root is not wiped — it is re-injected from disk. What does go is rules carrying paths: front matter and nested CLAUDE.md files in subdirectories, and they do not come back until a matching file is read again. For rules you want to persist, drop the paths: key or move them into the root CLAUDE.md.

Q5. Can I switch auto-compaction off?

You can (the autoCompactEnabled setting set to false, "Auto-compact" in /config, or the DISABLE_AUTO_COMPACT environment variable). It is not recommended. Switching it off does not reduce your context; you simply hit the ceiling and get an error. If what you want is for it to run earlier, the correct move is not to disable it but to narrow the window with /autocompact.

Q6. How many tokens does /compact consume?

It varies enormously with whether the cache is warm. Press it mid-session and the prefix is read from cache, costing, in the documentation's words, far less than the size of the context suggests. Press it after a break longer than the cache lifetime and the whole history is reprocessed uncached, making the same command as expensive as it ever gets. Cache lifetime is one hour on a subscription and five minutes by default through an API key or a cloud provider.

Q7. Can I specify what gets kept?

Yes. Write an instruction after /compact and the summary is produced with that focus (for example /compact keep the auth fix plan and the test results). If the same instruction works every time, create a # Compact instructions heading in CLAUDE.md and it applies as the default.

Q8. Why do responses feel slow right after a compaction?

The turn immediately after a compaction is not heavy. Per the documentation, that turn rebuilds the cache from a short summary, so it is not the slow part. What you are feeling is usually the compaction run itself, while the summary is being generated, or a case where you pressed it with the cache already cold.

Q9. Is there a feature called "micro-compaction"?

The behaviour exists — the documentation explains that old tool outputs are dropped first and the conversation is summarised only if needed, which is an explicit statement that something happens before summarisation. But as of 8 August 2026 the official documentation does not use the name "micro-compaction". The term comes from third-party write-ups, not from Anthropic, so treat it accordingly.

Related articles