catnap keeps Claude Code from compacting mid-task

In one developer’s long Claude Code sessions, 78 of 82 auto-compactions cut in while Claude was still working, according to a tally Claude produced for them. After they switched to catnap, the mod they shared on Show HN on October 20, the count fell to 0 of 129.

The code is in the catnap repository on GitHub. The mod doesn’t stop compaction from happening. It moves it to the end of whatever Claude is doing.

How a nap works

Claude Code compacts automatically when a conversation gets close to the context limit. It summarizes the history so far and carries on from that summary, so a full window never ends the session. The summary loses detail, though: an exact error string or a line Claude read two hours earlier can drop out. The compaction fires wherever the threshold happens to fall, and in this author’s sessions that was almost always mid-task.

catnap uses three thresholds. At 50% of the context window, it tells Claude how full the context is and asks it to finish its current task, write a handoff note and start the compaction itself. When Claude is done, catnap compacts and Claude picks the work back up from the handoff. The handoff replaces Claude Code’s default summary, so the same ground isn’t summarized twice. If Claude hasn’t compacted by 60%, it gets a stricter note. Claude Code’s own auto-compact still fires at 70% as a backstop. All three numbers are settings.

The author’s first attempt was a skill that made Claude save its progress explicitly throughout long runs. It cost more tokens and, in their words, \”didn’t fix the core problem.\” Mods, which are on by default from Claude Code 2.1.287, let them change when compaction happens instead.

What 129 naps showed

The 0-of-129 figure combines 98 compactions in benchmarks with 31 in the author’s own sessions. On cost, the author found catnap is the same as the default auto-compact firing at the same point, in both tokens and dollars, on 200K and 1M windows. Compared with the default compaction that waits until the window is nearly full, catnap used 56% fewer tokens.

The author also points out that most of that saving doesn’t need the mod: \”lowering the default auto-compact will get you most of the way there as well.\” Claude Code already has a setting for that. The CLAUDE_AUTOCOMPACT_PCT_OVERRIDE environment variable takes a percentage of the window and runs compaction there, so 50 compacts at half full. It can only lower the threshold. What catnap adds on top is the timing: Claude finishes its piece before the cut.

Memory was the author’s main worry, so they tested it. Claude worked through tasks one message at a time while 20 instructions and facts came up in the chat, inside long, chatty messages, and nowhere else. Right after compaction, with no file reads, Claude was asked to list them from memory. It listed all 20 in every run: 15 runs with catnap and 5 with the default compaction. Recall was identical, but catnap got there with a 4.0K-token handoff, 60% shorter than the default’s 10K. The test used made-up coding tasks on a 200K window.

The speed gain was something the author hadn’t set out to get. \”I was surprised that catnap is actually faster than the default option,\” they wrote. The default compaction makes a separate summary call. Under catnap, Claude writes the handoff in one go, and the note is shorter. Measured end to end, tasks finished in 406 seconds instead of 464, 58 seconds sooner.

The author lists compact-adviser, handoff-compact, session-pilot and sub-agent-compact as related tools. They say catnap adds two things: Claude finishes its piece first, and you get numbers on where the cut lands.

Checking your own logs

catnap works only with Claude Code and has been tested on Windows and Linux. It needs Claude Code 2.1.287 or later and installs with two commands: claude plugin marketplace add LippInc/catnap, then claude plugin install catnap@lippinc.

You can measure the problem before installing anything. npx github:LippInc/catnap prints how often auto-compact cut in mid-task in your own logs. It reads only the numbers and sends nothing.