Claude Code: When to Use /clear, /compact or a New Session

Claude Code: When to Use /clear, /compact or a New Session

To manage context in Claude Code, use /clear when the task has changed and nothing from the earlier conversation helps anymore. Use /compact when the task continues but the history has grown long and you want to keep the thread. Open a new session when you want to separate pieces of work or pick something up another day. In every case, anything that must always hold belongs in CLAUDE.md, not in the conversation.

Key takeaways

• /clear wipes the history of the current conversation and starts from zero, while your project files and CLAUDE.md stay in place.
• /compact replaces the history with a summary, so it saves space, but fine detail can be lost in the summary.
• A new session is the best choice for independent pieces of work, or when the conversation has already become muddled.
• Style rules, test commands and project constraints belong in CLAUDE.md, because it is read again at the start of every session.
• Before clearing or compacting, record decisions and open items in a file in the repository, so they do not depend on the memory of the conversation.

Why context fills up and what that changes in practice

Claude Code's context is everything the model can see in a conversation: your messages, its replies, files it has read, command output and tool results. That space is limited. For the underlying concept, the article on the context window in AI explains what it is and how to avoid overfilling it, and the piece on tokens in AI shows why that volume also affects cost.

The practical point is that context does not fill up with conversation alone. Reading a large file, a long test output or a search that returns many results takes up a lot of room. As the space nears its limit, two problems appear: Claude Code may compact the conversation automatically, and quality can drop, because older instructions get diluted among a lot of irrelevant material.

The technical literature on agents calls this context engineering: the goal is to keep in the window the smallest set of information that still lets the model do the task well. Anthropic describes this idea in its engineering post Effective context engineering for AI agents. The /clear and /compact commands are the two most direct manual tools for it.

A note on what is documentation and what is practice: what each command does is described in the official Claude Code documentation and may change between versions, so confirm it on the version you use. The recommendations here about when to use each one are implementation practice and working hypotheses, not guarantees.

What /clear and /compact do, and what each one loses

/clear starts a blank conversation inside the same project folder. The entire history is lost: what you asked, what the model answered, the decisions made along the way and the files it had read. What is not lost is the code on disk, the changes already saved and CLAUDE.md, which is loaded again.

/compact does something different. Instead of erasing, it asks for a summary of the conversation and continues working from that summary in place of the full history. You can add instructions after the command saying what to preserve, for example architecture decisions and the list of changed files. What is lost is detail: verbatim chunks of output, intermediate reasoning, discarded attempts and nuances the summary did not capture.

The difference in one sentence: /clear discards everything and relies on your files, while /compact discards the excess and relies on the summary. Both require the important state to live outside the conversation, that is, in the code, in notes and in CLAUDE.md.

If you do not compact, Claude Code may do it on its own near the limit. That is convenient, but it carries a risk: the automatic summary happens at a moment when you did not choose the focus. For that reason, compacting manually at a stable point in the task, with instructions about what to keep, usually gives more predictable results.

When to open a new session instead of clearing

Clearing the conversation and opening a new session look alike, but they suit different situations. A new session is useful when you want to keep the previous one available for reference or to resume later, while /clear is simpler when you just want to start over in the same terminal and do not need to go back.

Claude Code lets you resume earlier conversations (with options to continue the most recent one or pick one from a list, depending on your version's documentation). That makes a new session a cheap way to separate pieces of work without losing the history.

Prefer a new session in these cases:

• The task is independent of the previous one, such as moving from a bug fix to writing documentation.
• The conversation has piled up detours, failed attempts and corrections, and the model has started repeating mistakes you already resolved.
• You will continue on another day, or someone else is taking over.
• You want to test an alternative approach without contaminating the main one.

The idea of resuming work from explicit state, rather than from conversation memory, also appears in Anthropic's post Effective harnesses for long-running agents. The general lesson is the same: whoever hands the baton between sessions should leave a clear record of what was done and what remains.

Decision guide: clear, compact or start over

Use this sequence as a rule of thumb. It is a working hypothesis that each team should adjust with its own experience.

• Is the next task unrelated to the previous one? Use /clear.
• Is it the same task, the conversation is long, but the direction is right? Use /compact, with instructions about what to preserve.
• Is the conversation confusing, with many discarded attempts? Record the state in a file and open a new session.
• Did the model forget an important project rule? Do not repeat the rule in the conversation: put it in CLAUDE.md.
• Are you stopping and coming back later? Write the stopping point in a notes file and end the session.

And a short step-by-step for when you decide to compact or clear:

• Ask Claude Code for a summary of the current state: what was done, what remains and which decisions were made.
• Save that summary in a file in the repository, such as a task notes file, and review the text.
• Check that anything pending a commit has been saved or noted.
• Run /compact with focus instructions, or /clear if the task has changed.
• In the new conversation, ask it to read the notes file and confirm the next step before acting.

How to keep essential instructions in CLAUDE.md

CLAUDE.md is the project's file of persistent instructions. According to the documentation, it is read at the start of each session, which means it survives /clear and new sessions. It generally also remains in effect after compaction, but it is worth testing on your version: after compacting, ask the model which project rules it is following.

What to put in it:

• Commands to run tests, format code and start the local environment.
• Project conventions: folder structure, naming patterns, preferred libraries.
• Constraints: what must never be changed, which files are generated and which environments must not be touched.
• Security and data rules: do not paste credentials, do not read files containing customers' personal data, mask logs before analyzing them.
• A definition of done: what must pass before a task counts as finished.

What to leave out: task history, decisions that only apply this week, and long documentation text the model can read on demand. A bloated CLAUDE.md becomes noise and uses up context in every session. Keep it short, specific and verifiable. A rule like use format X for dates is better than write quality code.

For longer, repeatable procedures, it is better to separate them from CLAUDE.md. The article on Claude Code skills shows how to package team routines, and the piece on how to configure MCP in Claude Code explains the local, project and user scopes for connecting external tools without filling the conversation with instructions.

One simple habit helps: whenever you catch yourself repeating the same instruction across different sessions, that is a sign it should go in CLAUDE.md. And whenever a rule in the file stops being true, remove it. An outdated instruction is worse than a missing one.

Illustrative scenario and how we apply the method

Illustrative scenario: a small team maintains an online store's order system. In the morning, one person asks Claude Code to fix the shipping calculation. The conversation gets long, with many file reads and test outputs. Before lunch, shipping is fixed and she needs to adjust a screen unrelated to it.

The right choice is /clear, because shipping is finished and the screen is a different subject. Before clearing, she asks for a summary of what changed and saves it in a notes file. In the afternoon, while building the screen, the conversation grows again, but the task is on track, so she uses /compact and asks it to preserve the list of changed components and the decision about the field format. The next day, another person opens a new session, reads the notes file and carries on. The testing and style rules never had to be repeated, because they live in CLAUDE.md.

Applying the method we use in AI projects, the reasoning resembles any operation with agents:

• Map: observe how the team uses Claude Code today, where sessions get lost and which instructions get repeated.
• Limit: define what CLAUDE.md may contain, what it must not (personal data, credentials) and which folders or commands require approval.
• Pilot: test the routine of clearing, compacting and keeping notes on a real project, with an agreed criterion, such as less rework caused by repeated instructions.
• Hand over: document the routine, deliver the reviewed CLAUDE.md and decide whether to expand, adjust or stop.

If the people using it do not write code, the article on Claude Code for non-programmers covers terminal automation with the same precautions.

Frequently asked questions

Does /clear delete my code or CLAUDE.md?

No. /clear only erases the history of the current conversation. Files on disk, including code you have already saved and CLAUDE.md, stay as they were, and CLAUDE.md is read again at the start of the new conversation.

Is it better to compact manually or wait for automatic compaction?

In general, compacting manually at a stable point gives you more control, because you can say what to preserve. Automatic compaction works as a safeguard when the limit approaches, but the summary happens without your focus. Since behavior can change between versions, check the official documentation.

What should I do when the model forgets a project rule after compacting?

First, check that the rule is in CLAUDE.md and that it is written in a short, verifiable way. If it only existed in the conversation, it may have been lost in the summary. Move the rule into the file and, if needed, open a new session to make sure it is loaded.

Can I put customer data in CLAUDE.md or in task notes?

It is not recommended. Instruction files and notes live in the repository and may be shared, so they should hold rules and decisions, not personal data or credentials. If the work involves customer data, review your obligations under LGPD, including international transfer, in the article on international data transfer under LGPD when using AI providers.

Sources

• Anthropic: Effective context engineering for AI agents
• Anthropic: Effective harnesses for long-running agents