What is catnap?
catnap is a plugin for Claude Code that manages when Claude compacts a conversation as its context window fills. It gives Claude an early prompt to finish its current piece of work, write a handoff note and compact at a clean break, rather than waiting until the window is nearly full. The handoff lets Claude continue without a separate summary model call by default, and settings let users adjust the thresholds and behavior.
catnap Features:
Context Thresholds: The plugin can prompt Claude at configurable percentage or token thresholds, using whichever threshold is reached first.
Handoff Compaction: Claude writes a note about its next step and catnap uses that handoff in place of a generated conversation summary by default.
Automatic Continuation: After compaction, catnap sends Claude a message directing it to continue from the handoff, without requiring the user to type a follow-up.
Manual Controls: Users can start the compaction loop with a command, check local Claude Code logs with another command, or turn the plugin off.
Save Before Compacting: An optional save_step setting runs a command to save work before compaction, while catnap can keep a copy of the handoff.
Agent Ports: Alongside Claude Code, the project includes ports for OpenCode and Gemini CLI, with different compaction behavior for each agent.
catnap Benefits:
Fewer Midtask Breaks: By asking Claude to reach a clean stopping point before compacting, catnap can reduce interruptions while a task is in progress.
Less Waiting: Using Claude's handoff instead of a model-generated summary avoids waiting for a separate call to read and summarize the conversation.
Clearer Resumption: A handoff written at the end of a piece of work gives Claude a named next step to follow after its context is compacted.
Adjustable Behavior: Separate settings for soft prompts, strict prompts and automatic compaction let users choose how early the plugin intervenes.
Local Log Review: The check command reads numbers from local Claude Code logs without sending them off the machine, helping users inspect their own compaction history.
Use Cases:
Long Coding Sessions: Use catnap during extended Claude Code sessions where the context window may fill before a coding task has reached a natural stopping point.
Multi-Step Changes: For work spanning several pieces, such as a page, section or feature, let Claude finish its current piece and record what it should do next.
Test-Then-Continue Work: When Claude's last action runs tests or another check, the handoff can tell it to inspect the result as its next step after compaction.
Compaction History Checks: Run the check command to review local log numbers and see how often previous automatic compactions occurred during a task.
Custom Save Routines: Configure a save command for sessions where work should be saved before Claude compacts and resumes from its handoff.

