How compactly works

compactly has three modes: auto (the default), suggest, and off. In auto, it can ask Claude Code's configured model to judge a likely task boundary and then compact with handoff instructions. It does not guarantee that every boundary is detected or that every decision is right.

Prompt-time boundary check

With the default judge=sonnet, when a new prompt arrives and the context is at least minTokens (150,000 by default), compactly sends a short session digest and the new prompt to Claude Code's selected model. If the model finds a natural break with sufficient confidence, compactly holds that prompt, compacts the conversation with handoff instructions, and resubmits the prompt in the same session. Prompts containing attachments or @ mentions are not held for this path. SDK-host prompts are not held either.

The handoff asks Claude to retain completed work, open work, paused or blocked reasons, decisions and their reasons, relevant paths, unresolved failures, and (for a prompt-time check) the next prompt up to 500 characters.

If no prompt follows a task boundary

A successful configured signal such as a commit, push, or pull request can arm a timer when the context is large enough. With a judge enabled, compactly may compact shortly before the configured cache expires if no prompt follows. A new prompt cancels the timer. It runs only while Claude Code remains open and checks the context threshold again before acting.

In suggest mode, compactly can suggest /compactly after a configured boundary signal and completed turn. With judge=off, the configured signals control automatic behavior instead of a model judge. Set mode=off to disable automatic and suggestion behavior.

Paused work and feedback

Recent wording that suggests work is paused, blocked, or waiting suppresses signal-triggered automatic compaction. This check is heuristic; a model judge can still evaluate the next prompt. After an automatic compaction, a thumbs-up or thumbs-down changes the confidence threshold used by later judgments. Rating digests stay associated with the project where they were given.

Limits and costs

The judge can be wrong and may compact in the middle of work. Use suggest if you want to confirm a signal-triggered compaction yourself, or off if you do not want automatic behavior. Keep Claude Code's built-in autocompaction enabled as a separate safety net.

The judge request uses Claude Code's configured model and can consume usage. compactly does not provide a general measured savings guarantee. The panel's savings are estimates based on observed token usage and pricing assumptions, not a promise of lower bills. See privacy and data handling and cost and cache.

View source on GitHub · Apache-2.0