Let the agent choose when to compact.
Claude Code can’t choose when to compact its own context. This tool lets the agent pick a clean stopping point, save what it needs and carry on by itself.
The supervision problem
A long task eventually fills an AI agent’s working context. Compaction makes room by condensing the conversation, but the timing matters: the agent may be halfway through a change or relying on details it has not written down.
Claude could not initiate compaction at a point it chose. I either had to watch the task and tell it when to compact, or let automatic compaction happen at a token threshold that might interrupt context-dependent work.
What I gave the agent control over
The agent picks a clean stopping point, writes a handoff note with its goal, decisions and next step, then asks for compaction. A background worker compacts the session, and a relay chat wakes it up to read the note and carry on.
The important product change is that context management becomes part of the agent’s work. I no longer have to monitor a long process just to choose its compaction moments.
Used for weeks of engineering on bound.less
I used this workflow on bound.less’s custom rasterizer after it had been built. The initial implementation was brittle, so the agent first reviewed and hardened it. It then analyzed performance, researched possible improvements and implemented them.
This work ran entirely unsupervised for multiple weeks, with the agent choosing its own compaction points and preserving the findings, decisions and next steps it needed to continue. The benefit was being able to leave it with a substantial engineering task without monitoring its context window.
Install it with a guided setup.
Download the ZIP, extract it, then double-click INSTALL.cmd. Python 3.10+ is required. Nothing runs until you open the installer.
- Sign in twice. Sign in to Claude Desktop, then separately to the Claude Code CLI: run
claude auth login(or openclaudeand use/login), then checkclaude auth status. Desktop login alone is insufficient: the CLI performs the compaction. Use the same local profile and verify the bundled CLI can authenticate too. - Review the defaults. The wizard explains the policy below, asks for your model’s context window, and offers custom thresholds, checkpoint rules and handoff preferences. It writes those choices into both the installed
SKILL.mdand the configuration the hooks read. - Set up a separate relay chat. Automatic continuation requires a Claude Desktop Code chat that you explicitly authorize to act as the relay. It needs Bash and Desktop cross-session messaging. Ask it for its desktop host session ID and enter that in the wizard. A generic subagent does not provide this capability.
- Apply, restart and test. Confirm the final policy and file changes, restart Desktop Code sessions, then try a disposable conversation. The installer preserves unrelated hooks/settings and creates backups. It never compacts, stops processes or sends messages during setup.
A clean stop, with room to prepare.
Default checkpoints for a 1M-token context window. The wizard proposes lower checkpoints for smaller windows; automatic limits vary by model and version.
| Context | Decision |
|---|---|
| 250K | Only at a hard pivot: the task is complete and the user has moved to a new subject. |
| 500K | Ordinary work: finish a coherent step and compact at a clean stop. |
| 650K | Token-heavy work: begin looking for that clean stop. |
| 800K | Start wrapping up, even during token-heavy work like reading large files. |
| 900K | Compact at the next clean stop, leaving headroom before the actual model limit. |
Never compact mid-edit. Save changes, finish applicable checks, record background work and write a durable handoff. The user’s explicit compaction plan takes precedence while leaving headroom.
To change it later, run the installed install.py --configure wizard. It updates both the real skill file and runtime policy together. These are this project’s settings; you do not need to know how to edit a skill by hand.
Relay setup and compatibility details
The installer creates ~/.claude/selfcompact/RELAY_SETUP.txt with a prompt you can paste into your chosen relay chat. If you leave setup for later, the installation stays disabled. Finish both logins and relay authorization, then rerun the wizard with --configure.
This package contains the custom Windows Desktop integration. A terminal-only skill does not supply Desktop’s restart behavior or cross-chat messaging; that messaging integration is required separately. The installer relies on your confirmations and cannot verify live compatibility. The operational worker can stop a verified session process tree after compaction.
GitHub CLI sign-in is optional for repository workflows. The downloadable ZIP and compaction itself do not require it.
See the full installation and rollback guide, Claude’s skills documentation ↗ and CLI sign-in documentation ↗.
Windows · Python 3.10+ · source included · in regular use
How the workflow works
- Choose a clean boundary. Context hooks announce checkpoints. The agent finishes its current step and writes the goal, decisions, background tasks and next action into a durable handoff.
- Compact with recovery state. When the turn ends, a Stop hook starts a detached worker. It waits for the session to go quiet, backs up its transcript and runs the bundled CLI’s built-in compaction, then stops the session’s process.
- Resume the plan. The desktop app reloads the session from the compacted transcript, right away or when an authorized relay’s message arrives. A start-up hook tells the agent it compacted, and it reads its handoff and re-reads the exact context files before continuing.
Why the ordering matters
The desktop app may restart a stopped session immediately. Compacting first, then stopping the verified process, lets the next session resume from the prepared state. Per-session files, backups, stale-request checks and atomic writes support recovery.
Implementation and limits
The tool uses Python, Claude desktop hooks, the bundled CLI and a durable handoff. It is a custom Windows desktop integration. Context thresholds depend on the selected model, and a message or background task arriving during compaction can race with the old session.