Skip to content

Claude Code

catnap keeps Claude Code from compacting mid-task

4 min read

Written by an AI model from the linked sources and checked against them by a second model. How we work

All about: Claude Code versions and changes →
Image: github.com

The developer behind catnap, a Claude Code mod shared on Hacker News on October 20, says 78 of 82 auto-compactions in their long sessions hit while Claude was mid-task, a count Claude itself produced, and that none of 129 compactions did after the switch. If your long sessions keep compacting in the middle of work, the author’s own figures also point to a cheaper first step: lowering Claude Code’s default auto-compact threshold gets you most of the token savings, and catnap adds the part where Claude finishes its piece and writes its own handoff before the cut.

The code and install instructions are in the catnap repository on GitHub. The threshold the author refers to is one Claude Code already exposes. You can set it with the /autocompact command, the claude --autocompact flag, the CLAUDE_CODE_AUTO_COMPACT_WINDOW environment variable or autoCompactWindow in settings.json, which takes 100,000 to 1,000,000 tokens. The environment variable beats the other three. With nothing configured, Claude Code compacts when the conversation reaches the model’s context limit, though some sessions compact earlier, among them Opus 4.8 and Opus 5 on a 200K context window.

How the nap works

At 50% context, catnap tells Claude how full the context is and asks it to finish what it’s working on, write a handoff and then start compaction itself. Once the task is done, catnap compacts and Claude picks the work back up from the handoff. That note replaces Claude Code’s default summary, so the session doesn’t pay to summarize the same ground twice.

If Claude still hasn’t compacted by 60%, it gets a stricter note. At 70%, Claude Code’s own auto-compact kicks in as a backstop. All three thresholds are settings.

Before catnap, the author tried a skill that had Claude save its progress explicitly throughout long runs. It cost more tokens and didn’t stop compaction from landing mid-task.

What the author measured

Of the 129 compactions counted after the switch, 98 came from benchmarks and 31 from the author’s own sessions. On cost, the author says catnap matches the default auto-compact set to fire at the same point, in both tokens and dollars, on 200K and 1M context windows. Compared with the default compaction that waits until the context is nearly full, catnap used 56% fewer tokens. Most of that gap comes from compacting earlier, which is why a lower default threshold gets you most of the way there.

The memory test was narrower. Claude worked through tasks one message at a time while 20 instructions and facts came up only in the chat, buried in long, chatty messages. Right after compaction, with no file reads allowed, 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 came out identical. The difference was the size of what carried it: catnap’s handoff ran 4.0K tokens against 10K for the default summary.

Speed was the one result the author says they weren’t aiming for. Measured end to end, tasks finished in 406 seconds instead of 464, 58 seconds sooner. The author puts this down to Claude writing the handoff in one go, where the default makes a separate summary call, and to the note being shorter.

All of these figures are the author’s own. The memory test used made-up coding tasks on a 200K window, and the default side of it had five runs.

Who can run it

catnap works with Claude Code only and has been tested on Windows and Linux. It needs Claude Code 2.1.287 or later, the version where mods are on by default. The author lists compact-adviser, handoff-compact, session-pilot and sub-agent-compact as related tools, and says what catnap adds is that Claude finishes its piece first, plus the numbers on where the cut lands.

Installing takes two commands: claude plugin marketplace add LippInc/catnap, then claude plugin install catnap@lippinc.

To see whether you need it at all, npx github:LippInc/catnap runs with nothing installed and prints how often auto-compact cut in mid-task in your own logs. The author says it reads numbers only and sends nothing.

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.