prep-compact
Claude Code's auto-compact fires late and its generic summary often drops the files, decisions, and blockers you needed. The post-compact se
Open source Open in the app JSON README (API)
About
Claude Code's auto-compact fires late and its generic summary often drops the files, decisions, and blockers you needed. The post-compact session then veers off course. prep-compact nudges you earlier: a UserPromptSubmit hook watches your transcript's byte delta since the last compact. When it crosses a configurable threshold (default 4 MB ≈ 450K tokens on Opus 4.7), Claude is prompted to invoke the prep-compact skill, which drafts a tailored /compact <mini-schema> covering goal/next/files/decisions/state. You paste, run /compact, and the post-compact session resumes correctly. Invoke /prep-compact:prep-compact manually any time to refresh the draft before compacting.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- koenvdheide
- Origin
- marketplace
- Category
- ferramentas
- Last push
- 2026-06-27T12:07:20Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
koenvdheide/prep-compact/prep-compact
README
# prep-compact
## Why
Claude Code's auto-compact misses important details and runs late in the 1M Opus context window. Context is usually already degrading by the time it fires, and the default summary it generates is pretty iffy. It often doesn't save which files, decisions, or blockers you wanted preserved, and it forgets what subagents were running. A second compaction in the same session has no memory of anything that happened before the first. Running `/compact <instructions>` with a tailored prompt gives dramatically cleaner resumption, but requires you to remember to do it and design the prompt.
This plugin nags you at the right moment and drafts the tailored prompt for you. It presents an up to date tailored prompt by keeping a small running record on disk between turns (that records which files you've touched, what tools you use, what you've been asked to do, which subagents are active etc.) and folds that into every draft, so the resumed session carries forward state from the *whole* session, not just what was still in memory at the moment of compaction.
## How It Works
A Claude Code plugin that nudges Claude to prepare tailored `/compact` instructions when the context window is getting full enough that performance has started dropping. Experience suggests this happens around the halfway point of the 1M-token window on Opus.
CC does not programatically expose how many tokens are in use for the current session (even though we can see ourselves with /context), so there is no direct way to fire a reminder based on the current session's token use. However, CC does store how many tokens are in use at the moment of a given user prompt in its transcript file. This plugin works by firing hooks that read the tail end of this transcript file. Under the hood it works like this:
> Between turns, a `Stop` hook tail-reads the transcript and writes a continuously-updated handoff file at `${CLAUDE_PLUGIN_DATA}/handoff-<sid>.json` listing every file the session has touched (cumulative across `/compact` cycles), the most recent user requests quoted verbatim, in-progress todo items, and any active subagent launches.
>
> A `UserPromptSubmit` hook fires on every prompt submission. It tail-reads the last 256 KB of the transcript `.jsonl`, parses the newest main-chain (`role=='assistant'`, non-sidechain, non-api-error) `.message.usage`, and sums `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. When that total crosses `CLAUDE_CONTEXT_WARN_TOKENS` (default `450000`), an informational reminder names the handoff path and points the user at `/prep-compact:prep-compact`.
>
> The skill reads the warm handoff (extractive fields: cumulative file paths, recent user-message quotes, in-progress todos, recent Task launches) and adds an analytical layer (decisions, constraints, blockers, verb-anchored next-step) to emit a copy-paste `/compact <mini-schema>` block preserving what the post-compact session needs to resume correctly.
The reminder fires once per threshold-crossing. Once the token count drops back below the threshold (after you `/compact`), the flag is auto-cleared on the next turn and future crossings re-arm cleanly. You can also invoke `/prep-compact` manually at any time to refresh the draft right before running `/compact`.
The skill resolves *this* session's own handoff by its Claude Code session id (not by newest-modified file), so when several sessions run in the same project, `/prep-compact` reads the invoking session's own record and no other. If no matching handoff exists yet (none written, or you changed directories), or the session id is unavailable, it falls back to surveying the live conversation — never another session's data.
## Install
Add the `agent-tools` marketplace and install the plugin:
```text
/plugin marketplace add koenvdheide/agent-tools
/plugin install prep-compact@agent-tools
```
Run `/reload-plugins` if you installed mid-session.
## Requirements
- **Claude Code with plugin support.** If `/plugin` is unknown, update Claude Code.
- **Python 3** on `PATH` (as `python3` or `python`). The hook uses Python's `json.load` for robust stdin parsing.
## Configuration
One env var controls the threshold:
| Variable | Default | Meaning |
| --- | --- | --- |
| `CLAUDE_CONTEXT_WARN_TOKENS` | `450000` | Real token count (summed `input_tokens + cache_creation_input_tokens + cache_read_input_tokens` of the newest main-chain assistant turn, read from the transcript `.jsonl`'s `.message.usage`). When this crosses the threshold, the reminder fires. |
Set it in your shell profile or `~/.claude/settings.json` under `env`:
```json
{
"env": {
"CLAUDE_CONTEXT_WARN_TOKENS": "450000"
}
}
```
## Security and privacy
The hook reads `session_id` and `transcript_path` from stdin. Nothing is sent over the network. `session_id` is validated against `^[A-Za-z0-9_-]{1,64}$` before use as a filename; exotic values fall back to a SHA-1 hex hash. The flag file is an empty presence marker — no content recorded.
See [PRIVACY.md](PRIVACY.md) for the full statement.
## Known limits
- **Undocumented transcript format.** The hook parses `.message.usage` from the transcript `.jsonl`, which Anthropic doesn't officially document. Silent no-op if the schema changes.
- **Manual invocation.** The reminder is informational — it names the warm handoff path and points at `/prep-compact:prep-compact`. Claude does not auto-invoke the skill; type `/prep-compact` manually when you're ready to compact.
- **Staleness across turns.** The Stop hook refreshes the warm handoff after every assistant message, so `/prep-compact` reads current state. If the conversation has been idle and the handoff has been updated since the last user prompt, the draft will reflect that. There's a one-turn window of stale handoff right after `/compact` runs (UserPromptSubmit fires before the next Stop), but the next assistant turn refreshes it.
- **Session-id reliance.** Binding uses the `CLAUDE_CODE_SESSION_ID` runtime variable. If a future Claude Code stops exposing it, the skill degrades to an in-memory survey (no warm handoff), which is safe but less complete.
## License
MIT. See [LICENSE](LICENSE).