Claude Code auto-compact or a handover note: when each fits
Claude Code’s context window holds your whole conversation, and auto-compact summarizes it when the window fills. Compaction keeps your requests and key code but can drop detailed instructions from early on. You can steer it with /compact and a Compact Instructions section, or hand the work to a fresh agent with a written note. Working alone, the built-in tools are enough; a note pays off when other agents depend on the one running out of room.
Key numbers
- 967K
- tokens: where models with a native 1M window compact by default, before the window fills (Claude Code docs)
- 200K
- tokens: the boundary in other setups, such as Sonnet 4.6 and Opus 4.6 without extended context (Claude Code docs)
- 3.4×
- heavier: a step at 400–700K tokens of context against one under 100K, in our own week of data
- 40%
- of the window: the default point at which harnsy tells a lead that a seat should hand over (v0.7.0)
In this article
What the context window holds, and what happens when it fills
The context window is everything the model sees on a step. Anthropic’s docs list it: your conversation history, file contents, command outputs, CLAUDE.md, auto memory, loaded skills and system instructions. Claude Code sends all of it with every request, so the window only grows until something shrinks it.
What shrinks it is compaction. The docs describe it in two sentences: Claude Code “clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost.” That last clause is the part to plan around.
It does not wait for a full window. By default, models with a native 1M window compact “at about 967K tokens”; in setups with a 200K window, such as Sonnet 4.6 and Opus 4.6 without extended context, compaction happens at that 200K boundary. You can move the line yourself: /autocompact 500k sets a window between 100K and 1M tokens.
What you can do inside Claude Code
Most of it is about not losing the instructions and choosing when compaction happens:
- Put rules that must last in CLAUDE.md, not in the conversation. The docs say so in as many words: persistent rules belong there, because early instructions can be lost.
- Tell the summary what to keep: a “Compact Instructions” section in CLAUDE.md, or
/compactwith a focus, such as/compact focus on the API changes. - Compact at a natural break, between tasks, instead of letting it trigger in the middle of one. The prompt-caching docs give the same advice.
- Use
/clearwhen the next task is unrelated;/renamefirst if you want to find the old session again with/resume. - Run
/contextto see what takes the space, and send verbose work, such as test runs or log reading, to a subagent, which has its own window and returns only a summary.
If a single file or tool output is so large that the context refills right after each summary, Claude Code stops auto-compacting after a few attempts and shows an error instead of looping.
Compaction costs tokens too
Compaction is a request like any other, and its price depends on the cache. To write the summary, Claude Code sends the whole history plus an instruction. While the cache is warm, that request reads the history from cache and “costs a fraction of what the context size suggests”. After a break longer than the cache lifetime (one hour on a subscription, five minutes on an API key or once you draw on usage credits) nothing is cached, and the history is processed at full price. Then the summary replaces the history, so the next request shares no prefix with the old one and the conversation cache is built again.
So size matters twice. In our own week of Claude Code data, a step at 400–700K tokens of context was 3.4 times heavier than a step under 100K (the week’s numbers). A window that is allowed to grow long is expensive to keep and expensive to compact.
The other way: a handover note and a fresh agent
Compaction keeps one conversation going, and the summary is written by the agent that is already crowded. A handover does the opposite: the agent stops at a boundary, writes down what the next one needs, and a new agent starts with an empty window and that note. In harnsy this procedure is part of the instructions every agent reads.
Where each one steps in
- Each role has a handover point, by default 40% of the window, which a lead can set per role. When an agent crosses it, harnsy sends one message to the lead above it; if nobody is above, the person sees an item on the dashboard.
- The agent stops taking new work and writes a note outside the project, never committed: the goal, the areas it owns, the open threads, the decisions and why, the next steps, where the tests live. It commits only its own finished work and tells the lead the note’s path.
- The lead opens a replacement on the same role. The replacement reads the note and confirms to the lead. Only then is the old agent released; until then it stays as a consultant.
- The replacement takes the role’s open tasks. The tasks, the message log and the role itself live in harnsy’s database, not in anyone’s window, so they are still there.
One rule sits in the instructions because it is easy to get backwards: never compact in the middle of a task before the note is written. The agents are told to write first.
We use this ourselves: at the turn of September and October the frontend, designer and copywriter of our site team handed over this way. Each time the successor confirmed to the lead before the old agent was released.
Which to use
| Compaction | Handover and a fresh agent | |
|---|---|---|
| Who starts it | Claude Code near the limit, or you with /compact | The agent, at its role’s threshold, or when the lead asks |
| What carries over | A summary of the conversation: your requests and key code; early detailed instructions may be lost | What the note says, and the tasks, messages and roles harnsy keeps outside the window |
| What it costs | One summarization request over the whole history | A turn or more to write the note; the new agent reads it; the old one stays as a consultant until released |
| Where it can fail | What the summary leaves out is gone from the conversation | The note holds only what its writer thought to write down |
| Fits best | One agent, one task, no natural place to stop | A role others depend on, such as a lead or a reviewer, at a task boundary |
In short: if you work alone in one conversation, put the rules in CLAUDE.md, compact at a break and /clear between tasks; Claude Code already has what you need. The handover earns its place when several agents depend on each other and one of them is at the edge of its window.
What we do not know
- We have not compared what a summary keeps with what a note keeps on the same work. The table is about how they work, not which is better.
- We have not measured how often our agents lose an early instruction to compaction, and we do not claim that a handover prevents forgetting: the note holds only what its writer wrote down.
- The 3.4× comes from a single machine in a single week. It shows what happens in one setup, not in yours.
Sources
- Claude Code, “How Claude Code works”, “When context fills up”: code.claude.com.
- Claude Code, “Manage costs effectively”, “Manage context proactively”: code.claude.com.
- Claude Code, model configuration, “Set the auto-compact window” and the default thresholds: code.claude.com.
- Claude Code, “How Claude Code uses prompt caching”, “Compacting the conversation” and “Cache lifetime”: code.claude.com.
- harnsy, handover and roles.
Give each role a handover point
harnsy tells the lead when an agent crosses its threshold, keeps the roles, tasks and messages outside the window, and seats the replacement on the same role.
Install harnsyharnsy is not affiliated with Anthropic, OpenAI or OpenCode; their names are theirs.