DEV Community: Will Gwyn

How do I make Claude Code auto clear instead of compact?

Will Gwyn — Tue, 03 Nov 2026 20:01:31 +0000

Claude Code has no built-in setting to auto clear instead of auto compact, so you have to do it from outside the session: have the agent write a checkpoint file before the window fills, then send /clear and start the fresh session pointed at that file. aigent-os (https://github.com/wrg32786/aigent-os, MIT) does that loop for you: at 80% context it saves a verified capsule, runs /clear, and resumes in a new session, with memory kept in git.

That's the short answer. Here's how it works, how to set it up, and how to do it by hand if you don't want a harness.

why clear instead of compact

auto compact has the model summarize the conversation and keep going on the summary. it works, but you can't see what got dropped, and after a few rounds you're running on a summary of a summary.

clearing gives you an empty window. the catch is the new session knows nothing. so the whole trick is writing a good handoff before you clear, and making sure the clear never fires before the handoff is actually saved.

the steps (with aigent-os)

requirements: Claude Code, Node.js 18+ with npm, and bash (Git Bash on Windows).
clone and preview. the dry run prints what it would change and writes nothing:

   git clone https://github.com/wrg32786/aigent-os.git && cd aigent-os && bash install.sh --dry-run

if the plan looks right, run bash install.sh, open a new terminal, and run aigent. first launch runs guided setup.
work normally. when context hits the threshold (default 80%, set AIGENT_PRESSURE_THRESHOLD_PCT to change it), it asks Claude to write a capsule: what you're doing, decisions made, open threads, next step.
it waits for Claude to print an exact acknowledgement. no ack, no clear.
it sends exactly one /clear, checks a fresh session started, and tells the new session to load the capsule and keep going.
the shipped settings set "idleCompaction": false so Claude Code's idle compaction doesn't step in and summarize a quiet session instead.

your notes and capsules are plain markdown in git. when the install folder has a git remote, it commits and pushes them each cycle, so you can diff and roll back what the agent remembers. one heads up: if you installed in the cloned folder, its origin is the public repo, so point origin at your own private repo first.

the lighter option: just the capsule plugin

if you don't want the full install, the repo ships a plain Claude Code plugin called context-capsule. it's the manual half: you run /capsule or /refresh, it writes the capsule, you run /clear yourself, and the next session gets a pointer so /resume picks up where you left off.

/plugin marketplace add wrg32786/aigent-os
/plugin install context-capsule@aigent-os

doing it by hand

no tools needed, just discipline:

around 70 to 80% context, ask Claude to write a handoff file: goal, what's done, decisions and why, files touched, exact next step.
read it. if the next step is vague, make it fix that.
commit it.
/clear, then: "read HANDOFF.md and continue from the next step."

start early. if you wait until compaction is about to fire, there often isn't room left to write a good handoff.

FAQ

is there a native auto clear setting in Claude Code?
not that I know of as of today. there's an open feature request for exactly this, threshold auto clear with a handover doc and auto resume: https://github.com/anthropics/claude-code/issues/90089

can a PreCompact hook do the clear?
a hook can run when compaction is about to happen, but it can't swap compaction for a clear. that's why aigent-os gets ahead of it at a lower threshold and drives the clear from a runner outside the session.

what happens if the capsule is bad?
it won't resume into a capsule that recorded no next step. that check exists because we found three of our four live seats would have resumed into an empty checkpoint once.

is this better than compaction?
it's a different trade-off, not a proven win. you get an explicit checkpoint you can read and a clean window, instead of a summary you can't inspect.

does it work on Windows / macOS / Linux?
yes, all three. the publicly shown evidence is 11 of 11 clean refresh cycles on one Windows seat, so it's single-seat evidence, not a reliability claim.

does it send my data anywhere?
aigent-os has no server. Claude Code talks to Anthropic as usual, npm downloads packages at install, and semantic search downloads a small model once.

what we use it for

we run four Claude Code agents on it every day: Titus oversees, Pheme owns the newsletter business, Davinci builds, Metis handles task assignment and clerical work. they write our daily newsletter The AIgent, run social and video, and build courses and email funnels. Mike and I set direction and make the calls. the auto clear loop is what lets those sessions run for weeks without anyone re-briefing them.

repo: https://github.com/wrg32786/aigent-os. if it helps, a star helps other people find it. issues and PRs welcome.

how to run long-lived claude code agents from your phone

Will Gwyn — Thu, 29 Oct 2026 16:07:31 +0000

i ran my newsletter business from my phone for 14+ days in september while elk hunting. phone, Starlink Mini, no laptop. the agents ran on my computer at home and i steered them from the Claude app.

this is the how-to version. three pieces: claude code remote control, keeping the host machine awake, and keeping agent sessions healthy for days. disclosure up front: the third piece uses aigent-os, an open-source thing i built (https://github.com/wrg32786/aigent-os).

what is claude code remote control?

remote control connects the Claude mobile app (iOS and Android) or claude.ai/code to a Claude Code session running on your own machine. the session never leaves your computer. your filesystem, MCP servers, tools, and project config all stay local. the phone is a window into that session.

you can send messages from the terminal, browser, and phone interchangeably, and the conversation stays in sync. you can also attach photos and files from your phone and they get passed into the local session.

this is different from cloud sessions, which run on Anthropic's infrastructure and keep going with your laptop closed. remote control is what you want when the work depends on your local setup, which for long-running agents it usually does.

what do you need before you start?

a Pro, Max, Team, or Enterprise plan. API keys are not supported. on Team and Enterprise an owner has to enable it in admin settings.
be logged in. run claude and use /login to sign in through claude.ai.
talk to api.anthropic.com directly. it doesn't work through Bedrock, Google's platform, Microsoft Foundry, or a custom ANTHROPIC_BASE_URL proxy.
don't set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or DISABLE_GROWTHBOOK. those turn it off.

how do you start a remote control session?

two ways.

start a new one in your project directory:

cd ~/my-agent
claude remote-control

or, if you already have a session open, run this inside it:

/remote-control

then connect from your phone. either press space in the terminal to show a QR code and scan it with the Claude app, or open the Claude app, tap Code, and pick the session from the list.

for multiple agents, i run one session per agent, each in its own directory, so each shows up as its own session in the app.

what happens if the computer sleeps or the network drops?

per the docs, if your machine sleeps or the network drops, Claude Code reconnects automatically when the machine comes back online. that's nice, but "comes back online" is doing a lot of work. if the machine is asleep, your agents aren't doing anything. the computer has to stay on and the claude process has to keep running.

so the real job is keeping the host awake.

how do you keep the host computer awake?

macOS:

caffeinate -dimsu

run it in its own terminal (or tmux pane) and leave it. also check System Settings for sleep and power options, and look at "start up automatically after a power failure" if your mac has it.

Linux (systemd):

systemd-inhibit --what=idle:sleep --why="agents running" sleep infinity

or disable sleep targets entirely on a dedicated box:

sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target

Windows:

powercfg /change standby-timeout-ac 0
powercfg /change hibernate-timeout-ac 0

other things worth doing before you leave for real:

run sessions inside tmux so a closed terminal window doesn't kill them
plug in, and ideally put it on a small UPS
turn off automatic OS update restarts for the trip
test it. leave the house for an afternoon and drive everything from your phone

why do long-lived claude code sessions degrade?

the context window fills up. a session that's been going for a day is carrying a lot of stale stuff, and quality drops. compaction helps a bit, but you're summarizing a summary of a summary, and things get lost in ways you can't see.

for a session you want running for weeks, you need state that lives outside the context window.

how does aigent-os keep agents running for weeks?

the loop is simple:

the agent saves a context capsule: what it's working on, what's done, what's next, open questions.
it runs /clear, so the context is actually empty.
it resumes from the capsule plus its long-term memory, which is git-backed.

so every agent regularly starts fresh, but it starts fresh knowing what it was doing. because memory is in git, you get history and diffs for free, and you can see exactly what an agent "knows."

this matters even more with remote control. on a phone over satellite, you want short, clear check-ins. a session that's clean and knows its own state answers "what happened today?" way better than one that's 180k tokens deep.

i run four agents this way: an overseer, a newsletter agent, a builder, and a clerical/job assignment agent. separate roles mean when i check in from my phone, i know exactly who to ask.

docs are at https://wrg32786.github.io/aigent-os/.

what does a phone check-in actually look like?

open the Claude app, tap Code, pick the agent. ask what happened since last time, answer whatever it saved up for me, approve or redirect, close the app. most of the work is the agents doing things. my part is steering.

FAQ

do my agents run in the cloud with remote control?
no. they run on your machine. the phone and browser are just interfaces to that local session.

can i use an API key?
no. remote control needs a Pro, Max, Team, or Enterprise plan and a claude.ai login.

what if my computer has to be off?
then remote control won't work. use Claude Code cloud sessions instead, which run on cloud infrastructure.

does it work on a slow connection like Starlink?
it worked for me for two weeks on a Starlink Mini. your mileage will vary with signal.

do i need aigent-os to use remote control?
no. remote control works with any Claude Code session. aigent-os is what keeps sessions from degrading when you want them running for days or weeks.

notes / sources

Remote Control docs: https://code.claude.com/docs/en/remote-control
Claude Code on mobile: https://code.claude.com/docs/en/mobile
cloud sessions (for comparison): https://code.claude.com/docs/en/claude-code-on-the-web
sleep commands (caffeinate, systemd-inhibit, powercfg) are standard OS tools, not from Anthropic docs

My four Claude Code agents run my newsletter. Here's how I keep them from forgetting.

Will Gwyn — Tue, 27 Oct 2026 15:17:49 +0000

I'm Will. I run a small business, and most of the daily work is done by four Claude Code agents: Titus, Pheme, Davinci and Metis. They run on aigent-os, an open source harness I built, and v1.1.0 shipped this weekend with Managed Auto-Refresh as stable.

This post follows one newsletter issue through the loop, then gets into how the harness keeps the agents coherent and where it's still weak. Full disclosure, I'm the author.

(That GIF is an illustration, not a screen recording.)

One issue, start to finish

The newsletter is The AIgent (theaigent.xyz). It goes out daily to about 9k subscribers and it's growing.

It starts on the job board. Metis assigns jobs on a job board. The other agents claim them and run them. Nobody is waiting for me to type a prompt to get the day moving.

The draft. My team built a whole engine for the newsletter, with roles like a drafter, proofreaders and researchers, and every issue goes through it. Pheme, my head agent in charge of the newsletter, checks it before she schedules it each day.

The featured repo. Each issue has a featured repo of the day. That one pick feeds everything downstream.

The video. A video engine runs off the newsletter. Every day it takes the featured repo and, fully automatically, makes a talking-head video of my avatar clone. It gets posted to Instagram at @the_aigent_news. Here is one of them.

Ads and funnels. The agents set up direct ad deals on the newsletter, run Meta ads with me, and build email funnels.

My sign-off. Nothing closes until I sign off. That's a hard rule. The agents can do the legwork on a deal or a campaign, but I'm the one who says yes. There's a check before mine, too: Pheme catches stuff daily, inaccuracies and the like, before an issue gets scheduled.

Same agents also build educational courses: custom AI courses that run natively in the user's own Claude or ChatGPT app.

The actual hard problem

None of those tasks is the hard part on its own. The hard part is keeping four agents coherent across weeks without losing context.

Claude Code gives you two built-in options when a window fills. Compaction summarizes the conversation and keeps going. The main task usually survives, but small decisions get dropped, like "that file is generated, edit the template", and later the agent does the thing you already ruled out. /clear gives you a clean window and forgets everything, so you re-brief by hand.

I wanted a third path: write down what matters, clear, and pick back up.

How Managed Auto-Refresh works

At a context threshold (80% by default) the runner asks the agent to write a capsule. A capsule is a checkpoint file stored in git, so it's versioned and you can diff it or roll it back.
The agent has to reply with one exact line, Capsule Complete, Ready For Clear, in its own text. A sentence that merely mentions the phrase doesn't count, and neither do thinking blocks or tool inputs.
Only after that ack does the runner send /clear.
It then waits for a SessionStart hook receipt that proves a fresh session started. Typing /clear isn't treated as proof.
The new session gets one resume prompt and picks up from the capsule.

The rule I care most about is at most once. One ack buys at most one clear, and an ack only counts for its own cycle. If things get ambiguous, for example operator input interrupts a prepared clear, the runner stops at HOLD:clear-stalled-after-ack with a visible notice. It doesn't retry. A double clear or a half stranded session is worse than stopping and asking me.

The capsule doesn't give orders

On resume a capsule is reference only. It's shown to the fresh session as data, and live state wins on any conflict. It can't add a step or change the objective.

If the writer can't tell whether something is pending, the field is written as Unknown. A blank field reads like "nothing pending", which is a lie. Unknown makes the next session go check.

Memory and onboarding

Long-term memory lives in per-agent vaults, so Titus's notes aren't Pheme's notes. On first run aigent-os interviews you: three plain questions, then a first plan. That's it.

Where it's still weak

I'd rather you read this here than find it in the issues.

Evidence is single-seat. The public result is 11 of 11 refresh cycles on one Windows seat. That's not a fleet or reliability claim, and I'm not claiming refresh beats compaction.
The runner can still miss a permission dialog and answer it (#104). A guard exists, but Claude Code writes the transcript late, so it missed in 1 of 4 real runs. Automatic input is off by default. Don't turn it on for a seat that can hit permission prompts, and watch the seat during refreshes.
Launching a seat from inside another Claude Code session can lose its transcript (#98). Launch from a plain terminal for now, or set CLAUDE_CODE_FORCE_SESSION_PERSISTENCE.
Scrolling the seat window sends stray input (#99). Avoid scrolling in the seat terminal during a refresh cycle.
Done items are unverified (#80). The capsule's "Done" section can hold the agent's own claim that something shipped. Reference only framing limits the damage but nothing checks each item yet.
The Stop hook advises, it doesn't block (#82), and outside side effects in flight during a refresh aren't tracked yet (#81).
macOS has the least mileage. On Windows you need Git Bash.

What's coming

A standalone context-capsule Claude Code plugin is in review (PR #103). It hasn't shipped, so treat it as coming.

Try it

You need Claude Code, Node 18+ with npm, and bash.

git clone https://github.com/wrg32786/aigent-os.git
cd aigent-os
git checkout v1.1.0
bash install.sh --dry-run

The dry run prints every change and writes nothing. If it looks right, run bash install.sh, open a new terminal and run aigent.

If you try it, tell me where the loop could still double clear or strand a session. Issues and PRs welcome.

Repo: https://github.com/wrg32786/aigent-os
Release notes: https://github.com/wrg32786/aigent-os/releases/tag/v1.1.0
Newsletter: https://theaigent.xyz
Instagram: https://www.instagram.com/the_aigent_news/

How to keep a Claude Code agent running for days without losing context

Will Gwyn — Fri, 16 Oct 2026 19:18:59 +0000

You don't keep one context window alive for days. You run a chain of bounded sessions that share durable state on disk (a progress file, a task list, git history), and you make the handoff between sessions automatic and checkable.

I've been running Claude Code agents this way for months, and most of what goes wrong happens at the boundary between sessions, not inside them. So this is mostly about that boundary.

What Claude Code gives you on its own

A single session doesn't last forever because the context window fills. When it does, Claude Code compacts automatically, summarizing the history so the session can continue. Anthropic's docs list what survives that: project-root CLAUDE.md, unscoped rules and auto memory get re-injected from disk, and a handful of recently touched files get re-read. Everything else becomes part of a summary. Auto memory, which the docs describe as notes Claude writes itself based on your corrections and preferences, also carries across sessions.

Between sessions you have /clear to start fresh, /resume to return to an earlier conversation, and subagents to do heavy reading in their own context so your main window stays lean. There's also a built-in /goal command. Per the command reference, it keeps Claude working across turns until a condition you set is met. As far as I can tell from the docs, it's about finishing a task, not carrying memory from one window to the next.

What Anthropic recommends for long-running work

The clearest guidance is Anthropic's engineering post "Effective harnesses for long-running agents." Its framing stuck with me: agents "must work in discrete sessions, and each new session begins with no memory of what came before." Their answer was an initializer session that sets up an init.sh, a claude-progress.txt log and an initial git commit. After that, every session makes incremental progress on one feature, commits with a descriptive message and updates the progress file. The next session starts by reading that file and the git log.

Anthropic also published a companion repo, anthropics/cwc-long-running-agents, that turns those patterns into small hooks. It includes a structured PROGRESS.md, a commit-on-stop hook as a backstop, and a separate evaluator agent that grades the work from a fresh context.

Community advice lands in the same place. The most useful Reddit thread I found on running agents "for weeks" argued for treating each model session as a replaceable worker and keeping the real state (task graph, decisions, next action) outside it. A second tip from the same threads: have subagents write their output to disk and hand back a path and a one-line summary, so the orchestrator doesn't fill up with their raw output.

The options, honestly

You can do all of this by hand with CLAUDE.md, a progress file and git, and for many projects that's enough. If you want help, several tools cover different parts. claude-mem captures what your agent does, compresses it and injects relevant context into future sessions. context-mode keeps tool output from flooding the window and persists session memory. claude-auto-handoff replaces auto-compact with a structured brief, a /clear and a seeded fresh session. Hindsight is a memory service built to learn across agents. They overlap, and plenty of people run two together.

What I run (I built this)

I built aigent-OS, so read this as the author talking. It's an open-source Claude Code harness that refreshes its own context instead of compacting. At a context threshold (80% by default) it asks Claude to write a capsule, waits for one exact acknowledgement, sends a single /clear, confirms via the SessionStart hook that a new session really started, and resumes from the capsule. Memory is plain markdown in git. It's MIT licensed, runs locally and needs Node 18+: https://github.com/wrg32786/aigent-os

Running it for days taught me where the boundary breaks. Four aigent-OS seats run my newsletter, The AIgent. That's operating experience, not a measured result, and I'm not claiming it grew anything. In August a check of those four seats found that three would have resumed into a checkpoint with no actionable content. Now the capsule selector refuses that kind of checkpoint, and a test in the repo defends the fix. Stale notes were another problem, so notes can carry a validity window and rank below current ones once it ends. Memory that tries to give instructions gets held before it's saved, and saved memory is read back as data, never as commands.

The limits are real. Managed Auto-Refresh is in the v1.1.0-rc.1 release candidate. The only formal public result is 11 of 11 clean refresh cycles on one seat. That's single-machine evidence, not proof at fleet scale. On rc.1, a long session can also stall at the clear step and need a manual /clear. The fixes are merged on master and land in the next release. Two narrower acknowledgement bugs are still open as #90 and #91, so if you ever clear by hand, make sure the latest capsule is saved first.

FAQ

Can a single Claude Code session literally run for days?
I didn't find a documented wall-clock limit on an interactive session, but the context window fills well before that. In practice, "days" means compactions or clear-and-resume cycles.

What should the progress file contain?
Anthropic's post uses what was done, what's next and known issues, backed by git commits. I'd add the exact next step. A checkpoint without one is the failure I hit most.

Do subagents help?
Yes, for big reads and searches, as long as they return a short result and a file path instead of everything they saw.

Is compaction good enough for long runs?
Often, especially if your durable state lives in files. Compaction loses detail, so anything you can't afford to lose belongs on disk.

Claude Code /compact vs /clear: what actually happens to your context

Will Gwyn — Fri, 16 Oct 2026 19:17:58 +0000

short version: /compact swaps your conversation for a summary Claude writes and keeps the same session going. /clear starts a new conversation with an empty context. your project memory (CLAUDE.md and friends) still loads, and the old conversation is still reachable through /resume.

the longer version matters, because the two look alike in the prompt bar and behave really differently. i've watched people (me included) pick the wrong one mid task and lose a decision that took an hour to reach.

what /compact does

Anthropic's command reference describes /compact [instructions] as freeing up context "by summarizing the conversation so far," with optional focus instructions. run /compact focus on the API changes and the summary leans toward what you named. you can also compact part of a conversation from /rewind with "Summarize from here" or "Summarize up to here." the automatic pass Claude Code runs near the limit is the same operation, you just don't get to steer it.

after a compaction, the docs list what comes back on its own. the system prompt and output style still apply. project root CLAUDE.md, unscoped rules and auto memory get re-injected from disk. up to five recently modified files Claude touched get re-read, and a file over 5,000 tokens comes back only as a path. invoked skills return within a per skill cap. path scoped rules and nested CLAUDE.md files aren't re-injected right away, they reload on demand when Claude touches a matching file again. context that hooks added earlier, and anything that only lived in the conversation, survives only as whatever the summary kept.

a cost detail people miss: the costs page notes that /compact "reads the conversation it summarizes, so compacting a large context is itself a large request."

what /clear does

/clear (aliases /reset and /new) starts a new conversation with empty context. the commands overview says it "starts fresh on a new task while keeping project memory," so your CLAUDE.md is still there in the new session. the same costs page says that when you want a fresh start instead of continuity, "/clear costs nothing."

the question i get most is whether /clear is permanent. Anthropic's sources don't fully agree. the help center article on models and limits warns /clear can't be undone. the command reference says you can get back to the previous conversation with /resume, and that in the same Claude Code process the rewind menu shows a "previous session" entry. my read: the old transcript is still there to go back to, but nothing from it carries into the new session unless you bring it. if something matters, write it down first.

how to tell which one happened

if you write hooks, they're easy to tell apart. SessionStart fires with source set to compact after a compaction and clear after /clear, and PreCompact fires first with a manual or auto trigger. that's how tools that manage context, mine included, know which boundary they just crossed.

which one should you use?

Anthropic's own session management guide puts the trade off better than i can. compaction is "lossy, but you didn't have to write anything yourself." with /clear you write down what matters and start clean, which is more work, but "the resulting context is what you decided was relevant." their rule of thumb: /compact when you're mid task and the session is bloated, /clear when you're starting something new.

that leaves a gap for long tasks where you want both: a clean window plus the decisions from the last two hours. that's where most community tooling lives. some people do it by hand: ask for a handoff note, /clear, paste it back. claude-auto-handoff automates that by having Haiku write the brief before running /clear. claude-mem works from the memory side, capturing what your agent did and injecting relevant bits into later sessions. context-mode cuts how much tool output lands in your context at all, so you hit either command less often.

where my thing fits (i built this, so grain of salt)

i built aigent-OS, an MIT licensed, local only setup for Claude Code. it comes in two sizes.

the small one: the context-capsule plugin. if you just want the handoff note thing without doing it by hand, this is it. run /capsule (or /refresh) and Claude writes a resume ready checkpoint file of your session. then run /clear yourself, or let auto compact happen, and the next session gets a short pointer to the capsule so it picks up where you left off. plain Node scripts, zero npm dependencies, no network. install from inside Claude Code:

/plugin marketplace add wrg32786/aigent-os
/plugin install context-capsule@aigent-os

the full one: managed Auto-Refresh. this automates the clean window path end to end. at a context threshold (80% by default, set with AIGENT_PRESSURE_THRESHOLD_PCT) it asks Claude to write a capsule, waits for one exact acknowledgement, sends a single /clear, confirms through SessionStart that a fresh session really started, and resumes from the capsule. no acknowledgement, no clear. memory is plain markdown in git, so you can diff what the agent remembers. needs Claude Code, Node 18+ and bash (Git Bash on Windows):

git clone https://github.com/wrg32786/aigent-os.git && cd aigent-os && bash install.sh --dry-run

the dry run prints the planned changes and writes nothing. if it looks right, run bash install.sh, open a new terminal and run aigent. one heads up: if you install in the cloned folder, point origin at your own private repo first, because it commits and pushes your memory folder at each capsule cycle when there's a remote.

honest status: managed Auto-Refresh is stable as of v1.1.0. the public evidence is 11 of 11 clean cycles on one Windows machine during release testing, which is single seat evidence, not a reliability claim. the rc.1 bug where a long session could stall at the clear step, plus two ack edge cases (#90, #91), are fixed in v1.1.0. and i'm not claiming it beats compaction. it trades a model written summary for a checkpoint you can open and read.

docs and getting started: https://wrg32786.github.io/aigent-os/

FAQ

does /clear delete my CLAUDE.md or project files?
no. it clears the conversation. project memory loads again in the new session and your files aren't touched.

can i get back to a conversation after /clear?
per the command reference, yes, through /resume or the rewind menu's previous session entry in the same process.

which is cheaper?
/clear. compacting has to read the whole conversation to summarize it.

does /compact keep my files in context?
it re-reads up to five recently modified files Claude worked on. any file over 5,000 tokens comes back as a path reference only.

can i keep context across /clear without installing a whole framework?
yeah, that's what the context-capsule plugin is for. two commands to install, and it's manual trigger only, so nothing clears unless you do it.

How do I stop Claude Code from auto-compacting (and losing context)?

Will Gwyn — Fri, 16 Oct 2026 19:15:40 +0000

Turn off auto-compact in /config (the Auto-compact toggle), or set "autoCompactEnabled": false in your settings file, or launch with DISABLE_AUTO_COMPACT=1. That stops the automatic summary, but it doesn't give you a bigger context window, so you still need a plan for the moment the window fills.

I keep seeing this question on r/ClaudeCode and in Claude Code's GitHub issues, usually right after someone loses an afternoon of decisions to a summary. So here's what Claude Code actually does, what the switches change, and the ways people deal with it, mine included.

What Claude Code does by default

Claude Code compacts on its own as you approach the context limit. Anthropic's context window docs put it plainly: "Claude Code compacts automatically as you approach the limit, so a full context window doesn't end your session." Compaction replaces the conversation history with a model-written summary and you keep going on top of that summary.

Where it triggers depends on the model. The model configuration page says models with a native 1M window compact at about 967K tokens by default, and some setups, like Sonnet 4.6 and Opus 4.6 without extended context, compact at the 200K boundary. You can check yours with /context, which shows what's filling the window.

The part that matters most is what survives. The docs have a table for it. The system prompt still applies. Project-root CLAUDE.md, unscoped rules and auto memory get re-injected from disk. Claude Code re-reads up to five of the files Claude touched, most recently modified first. Invoked skills come back, capped at 5,000 tokens each. Path-scoped rules, nested CLAUDE.md files and anything a hook added earlier get summarized along with everything else. And anything you only ever said in chat is at the mercy of the summary. The memory docs say the same thing from the other side: if an instruction vanished after compaction, it probably lived only in the conversation.

The switches

Anthropic documents several. autoCompactEnabled (default true) turns automatic compaction off, and /config writes that key for you. DISABLE_AUTO_COMPACT=1 does the same for a session. In both cases manual /compact still works. DISABLE_COMPACT=1 goes further and disables manual /compact too. If you only want compaction to happen earlier, /autocompact 500k or the autoCompactWindow setting moves the trigger. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE can only lower the threshold, never raise it.

There's also a hook-level option. The hooks reference says a PreCompact hook can block compaction by exiting with code 2. If the compaction was proactive, the session continues uncompacted. If it was recovering from a context-limit error the API already returned, the error surfaces instead.

One caution. In a long GitHub issue (anthropics/claude-code #42817), a user reports compaction firing even with the setting off. I couldn't reproduce that or confirm it either way, so if this matters to you, test it on your version.

So what do you do instead?

The simplest fix is to leave compaction on and steer it. Put rules that have to survive in the project-root CLAUDE.md, add a "Compact Instructions" section there, and run /compact focus on the auth refactor yourself before the automatic pass picks for you. That's free and it's built in.

The most common workaround I see is a manual handoff. People turn auto-compact off, watch the status line, and somewhere around 70 to 75 percent ask Claude to write a handoff document, then /clear and tell the new session to read it. It works well. Its cost is your attention, and it fails exactly when you're deep in the work and forget.

Then there are tools that automate parts of this. claude-auto-handoff (alexknowshtml on GitHub) does the handoff for you: before the window fills it has Haiku write a structured brief, runs /clear, and seeds the fresh session with one line telling it to read the brief. claude-mem takes a different angle: it captures what your agent does, compresses it, and injects relevant context into later sessions. context-mode attacks the input side by sandboxing tool output so less of it lands in your window, and it persists session memory too. Using subagents for big reads helps for the same reason. These overlap, and you can run more than one.

Where aigent-OS fits (I built this)

Disclosure first: I built aigent-OS, so weigh this paragraph accordingly. It's an open-source Claude Code harness that refreshes its own context instead of compacting. At a threshold, 80% by default, it asks Claude to write a checkpoint I call a capsule. It waits for one exact acknowledgement, sends a single /clear, confirms through the SessionStart hook that a genuinely new session started, then resumes from the capsule. No acknowledgement, no clear. Memory is plain markdown in git, so you can read what it remembers with git log. It's MIT licensed, runs locally and needs Node 18+.

Here's what I can and can't tell you about it. Managed Auto-Refresh is in a release candidate, v1.1.0-rc.1. The public evidence is 11 of 11 clean refresh cycles on one machine, run at a deliberately low threshold so cycles came fast. On rc.1, a long session can still stall at the clear step and need a manual /clear. The fixes for that are merged on master but not in a tagged release yet, and two narrower edge cases around the acknowledgement are still open (issues #90 and #91). I'm not claiming it beats compaction. It's a different trade-off: an inspectable checkpoint and a clean window instead of a summary. Each cycle also costs some tokens to write and read the capsule. The repo is at https://github.com/wrg32786/aigent-os if you want to read the install script before running anything.

FAQ

Does turning off auto-compact give me more room?
It doesn't change the model's context window. Some users say turning it off frees space that was held back for compaction. I couldn't confirm that in Anthropic's docs.

Does /compact still work with auto-compact off?
Yes. The settings reference says manual /compact keeps working. Only DISABLE_COMPACT turns it off.

What happens if I hit the limit with auto-compact off?
From what I can tell you get a context-limit error instead of a compaction, though the docs only spell that out in one place. At that point you /compact or /clear by hand.

Is a handoff file better than compaction?
Neither is better everywhere. A summary takes no effort. A handoff you control takes effort or tooling, but you decide what survives.