Iterative Compaction
daily driverA quiet background assistant that keeps your AI sessions from forgetting what they were doing.
When you work with an AI assistant for a long time, the assistant can only hold so much in its head at once; eventually older details start to fall away. Iterative Compaction quietly watches the session and, at regular intervals, sends a separate background agent to write a concise running summary to disk. That summary survives restarts, handoffs, and even switching to a different assistant entirely.
- Python
- Bash
- Codex
The neat part is that it works entirely without interrupting anything. The main Claude session just keeps going while a second AI assistant (Codex) quietly steps in, reads what it missed, and folds it into a tight summary file. When a session ends or needs a fresh start, that file is right there, so nothing important gets lost. It's like having a note-taker in the room who doesn't say a word but always knows what happened.
What it does
AI assistants have a memory limit - they can only read so much of a conversation at once. Claude Code's built-in approach is to summarize everything in place when the limit is hit, but that means the summary happens suddenly, all at once. Iterative Compaction does it gradually instead: after every tool use, it checks the current "word count" of the session. When it crosses one of several preset thresholds (100k tokens, 150k, 200k, and so on), it quietly spawns a separate Codex agent in the background to update a rolling summary file on disk. That summary file (about 4-6k tokens, or a few pages) captures the key facts, decisions, and outcomes so far. When the session wraps up or needs to be handed off to a fresh assistant, the summary is there waiting. The next assistant picks it up and steps right in.
Why it's neat
It never interrupts
The background summarizer runs completely separately from the main session; you never wait for it or even notice it.
It only reads what's new
Each pass picks up exactly where the last one left off, so the work stays fast and doesn't repeat itself.
It outlasts the session
The summary file lives on disk, so restarting, handing off to a different agent, or coming back the next day all pick up right where things left off.
How it works
1. Watch the token count
After every action, the hook checks how many tokens the session has consumed and whether a new threshold has been crossed.
2. Spawn a background summarizer
When a threshold is hit, a separate Codex agent is launched quietly in the background with no interruption to the main session.
3. Fold new content into the summary
The background agent reads only the new portion of the transcript since the last pass and adds it to the rolling summary file.
4. Hand off cleanly
When the session ends, the prepare-handoff skill uses the summary file so the next session knows exactly what happened.