Compacting an Idle Claude Session Before Its Cache Goes Cold

I wanted to leave a long Claude Code session running, come back later, and continue from a shorter working summary instead of rereading the full conversation after its prompt cache expired.

That became claude-cache, a small plugin I released on 7 October. It watches the session's cache window and can compact an idle conversation while the existing prefix is still cached.

The useful part was deciding when it should leave the session alone.

The project's README visual illustrates the countdown and AFK note. The conversation shown is an example.

A summary has its own cost

A coding session accumulates instructions, tool results, patches, and decisions. Prompt caching lets a later request reuse an existing prefix. Anthropic documents five-minute and one-hour cache lifetimes; the lifetime runs from the start of the request that reads or writes the entry.

After that window, a summary still has to read the old conversation. Asking for one only when I return can put the expensive read before the smaller context I wanted.

The plugin tries to move that work into the warm window. It does not extend the provider's cache lifetime. It asks Claude Code to summarize while the prefix can still be reused, leaving a shorter conversation for the next request.

That is a timing strategy. I have not measured a subscription-wide saving from it.

The timer needs evidence and limits

I did not want every pause to trigger a summary.

The release reads the cache-creation usage fields in the session transcript to distinguish a five-minute cache from a one-hour one. Before it has that evidence, it can use the configured TTL and environment settings. The countdown exposes which window it is working with.

For a one-hour cache, ordinary automatic compaction starts after 55 minutes of inactivity. I kept it off for five-minute caches: a short coffee break should not routinely throw away detailed working context.

Automatic compaction also requires the conversation to fill at least 30% of the model's context window. It waits while a turn or another compaction is running, and it will not compact the same idle stretch twice. A manual or built-in compaction counts too; another one waits for new conversation.

A timer can wake late. If the laptop sleeps through the useful window, the plugin should not wake up and do the costly operation anyway. It requires at least 30 seconds before expiry to start. Past that point, it skips the compaction and reports the cold return.

The first command tried to compact inside its own turn

The first live failure was straightforward. I ran /cache compact, and Claude Code refused the call because the command hook was still holding the turn that compaction needed to replace.

The command handler was the wrong place to perform the operation.

I changed it to request compaction after the hook returns. The deferred callback checks the session state again and claims the compaction before starting it. That second check matters: another event can arrive between pressing the button and running the callback.

In a live session, the corrected command compacted roughly 42,000 tokens to 14,000. That established that the path worked in that session. It did not establish a typical compression ratio or a cost guarantee.

Leaving instructions is part of leaving the session

An idle session and an unattended job need different treatment.

Before leaving, I can write:

/cache afk finish the migration, then run the end-to-end checks

The plugin keeps that handoff note in the instructions passed to compaction. It asks the summary to retain the note, including when I use /compact myself. My next prompt turns AFK mode off and shows the note again.

AFK mode schedules closer to expiry: four minutes before a one-hour cache ends, or one minute before a five-minute cache ends. The warm-window and running-turn checks still apply.

The note gives the summary a concrete obligation. It cannot make summarization lossless. A compacted conversation can still omit a detail that later matters, so I want the original transcript available and the decision to compact visible.

What I released

Version 0.1.0 shipped under Apache 2.0, with a clean-configuration marketplace install check, type checking, and 21 plugin tests. The required CI target was Claude Code 2.1.292; a separate latest-version job provided an early warning about host changes.

I also inspected the host's built-in idle compaction during that work. Its availability and thresholds depended on the account and version. That comparison belongs to the October build record; I would check the current host before choosing a plugin on that basis today.

The repository contains the installation steps and controls. I use the per-session switch, countdown, and handoff note to make the timing explicit. If the useful window is gone, the plugin leaves the conversation alone.