DEV Community: Will Gwyn

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

/compact replaces your conversation with a summary Claude writes and keeps the same session going. /clear starts a new conversation with an empty context. Your project memory, like CLAUDE.md, still loads, and the old conversation stays available through /resume.

That's the short version. The longer version matters, because the two commands look alike in the prompt bar and behave very differently, and 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. The rest of the conversation, including path-scoped rules, nested CLAUDE.md files and context that hooks added, lives on only as whatever the summary kept.

There's 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 CLAUDE.md and auto memory load as usual 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 quite agree here. The help center article on models and limits warns that /clear can't be undone. The command reference says you can return to the previous conversation with /resume, and that in the same Claude Code process the rewind menu shows a "previous session" entry. My reading: 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, the two commands are 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 on claude.com gives 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 is /compact when you're mid-task and the session is bloated, and /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 of the 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 context into later sessions, so a fresh window starts less empty. context-mode reduces how much tool output lands in your context in the first place, which means you hit either command less often.

Where aigent-OS fits (I built this)

I built aigent-OS, so take this as the author's description. It automates the clean-window path. At a context threshold (80% by default) it asks Claude to write a capsule, a checkpoint file with the work state and next step. It waits for one exact acknowledgement, sends a single /clear, confirms through SessionStart that a new session really started, and resumes from the capsule. If the acknowledgement never comes, it never clears. Memory is plain markdown in git, so you can diff what the agent remembers. It's MIT licensed, runs locally and needs Node 18+: https://github.com/wrg32786/aigent-os

The honest status: Managed Auto-Refresh is in the v1.1.0-rc.1 release candidate. The public evidence is 11 of 11 clean cycles on one machine. On rc.1 a long session can still stall at the clear step and need a manual /clear. The fixes are merged on master and ship in the next release, and two smaller acknowledgement edge cases (#90 and #91) are still open. I don't claim it's better than compaction. It trades a model-written summary for a checkpoint you can open and read.

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?
According to 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. Larger ones come back as a path reference only.

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.