idle-compact
Compacts an idle session with a large context just before its prompt cache expires, while the summary still reads from cache
newcommandtoastprompttimer
Compacts an idle session with a large context just before its prompt cache expires, while the summary still reads from cache
A Claude Code mod that compacts a session you've walked away from, just before its prompt cache expires.
The prompt cache lasts an hour after the last request. Coming back later, your next prompt rewrites the whole context at the cache-write price, twice the input price. Compacting first means only the short summary gets written. Compacting just before expiry is cheaper still, because the summary call reads the context from cache at a fraction of the input price.
When the main conversation has had no request for 55 minutes and the context holds 120k tokens or more, the mod runs /compact and tells the summary to keep the open task, decisions made, files changed and anything left to do. A toast says when it happened. If a turn is running, nothing happens, and the mod waits for the next idle stretch.
If your computer slept or Claude Code wasn't running, the cache can expire without the timer firing. Then the first prompt you type on a cold cache with a large context is held back:
This first turn saves nothing. The summary call misses the cache and writes the whole context back to it, at about what sending the prompt as it was would cost, and nothing reads that cache again. The saving comes after, since every later turn reads the short summary from cache instead of the full context. Claude Code doesn't allow a mod to compact while a prompt is on its way, so holding it back is the only way to do this. Prompts with images attached are sent as they are, since the box can't hold the images.
A resumed session (claude --resume, or a restart) works out its cache age from the last reply in its transcript, so both the timer and the fallback cover it. The mod reads the transcript once at startup, from the default place under ~/.claude/projects.
The trade-off: a compaction loses detail. If you come back to a task in the middle, Claude may need to re-read a file or two. Raise the threshold or turn the mod off if that costs more than it saves.
/idle-compact shows the setting and what the mod sees now: the context size, how long ago the last reply was, and where the last prompt came from/idle-compact off and /idle-compact on turn it off and back on for the session/idle-compact 120k sets the minimum context size for this session/plugin install idle-compact --marketplace noash-xrc/claude-toolsAnswer y to add the marketplace, then pick a scope.
claude plugin marketplace update noash-tools
claude plugin update idle-compact@noash-toolsRestart Claude Code to load the new version.
MIT
hooks/register.ts 111 lines1import type { EngineInterface, Register } from 'claude-code'
2
3// ponytail: assumes the 1-hour TTL Claude Code uses on subscriptions, like context-meter
4const CACHE_TTL_MS = 60 * 60 * 1000
5// compact this long before the cache expires, so the summary call still reads from it
6const MARGIN_MS = 5 * 60 * 1000
7const INSTRUCTIONS = 'Keep the open task, decisions made, files changed and anything left to do.'
8const forPrompt = (text: string) => `${INSTRUCTIONS} Above all, keep what the next request needs: ${text.slice(0, 2000)}`
9
10let enabled = true
11let minTokens = 120_000
12// when the last main-thread request finished; undefined once compacted, until the next one
13let cachedAt: number | undefined
14// the session cachedAt belongs to: a resume (from the picker too) swaps it without a session.start
15let knownFor: string | undefined
16// what the last prompt was, for /idle-compact to report
17let lastPrompt = 'none yet'
18
19// A resumed session reports no size until its first reply, so fall back to the engine's local estimate (no API call).
20const contextTokens = async ($: EngineInterface) =>
21 (await $.session.usage()).context.tokens ?? (await $.session.usage({ breakdown: 'summary' })).context.breakdown?.totalTokens ?? 0
22
23// A resumed session has no request in this process yet, so its last reply comes from the transcript.
24// ponytail: reads the whole file once, and assumes the default ~/.claude/projects/<cwd with - for each symbol>/<id>.jsonl
25const lastReplyAt = async ($: EngineInterface, id: string) => {
26 const home = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${(await $.env.get('USERPROFILE')) ?? (await $.env.get('HOME'))}/.claude`
27 const folder = (await $.session.cwd()).replace(/[^a-zA-Z0-9]/g, '-')
28 const lines = (await $.fs.read(`${home}/projects/${folder}/${id}.jsonl`)).split('\n')
29 const last = lines.findLast(line => line.includes('"type":"assistant"'))
30 const at = last === undefined ? NaN : Date.parse((JSON.parse(last) as { timestamp?: string }).timestamp ?? '')
31 return Number.isNaN(at) ? undefined : at
32}
33
34// Reads the transcript once per session id, and only when this process has no request of its own for it.
35const cacheAge = async ($: EngineInterface) => {
36 const id = await $.session.id()
37 if (id !== knownFor) {
38 knownFor = id
39 cachedAt = await lastReplyAt($, id).catch(() => undefined)
40 }
41 return cachedAt === undefined ? undefined : (await $.clock.now()) - cachedAt
42}
43
44const ago = (ms: number) => (ms >= 2 * 3_600_000 ? `${Math.floor(ms / 3_600_000)}h ${Math.round((ms % 3_600_000) / 60_000)}m` : `${Math.round(ms / 60_000)}m`)
45
46export const register: Register = on => {
47 on('session.start', async ($, e, next) => {
48 const started = await next(e)
49 await $.command.register({
50 name: 'idle-compact',
51 description: 'Show or set compaction of idle sessions before the cache expires: on, off, or a minimum context in thousands of tokens',
52 argumentHint: '[on | off | <k tokens>]',
53 })
54 $.clock.every(60_000, async () => {
55 if (!enabled) return
56 const age = await cacheAge($)
57 if (age === undefined || age < CACHE_TTL_MS - MARGIN_MS) return
58 const tokens = await contextTokens($)
59 if (tokens < minTokens) return
60 cachedAt = undefined
61 // rejects while a turn runs; the next idle stretch tries again
62 const r = await $.session.compact({ instructions: INSTRUCTIONS }).catch(() => undefined)
63 if (r && !('skip' in r)) $.ui.toast(`idle-compact: compacted a ${Math.round(tokens / 1000)}k context before its cache expired.`)
64 })
65 return started
66 })
67
68 on('command.run', { command: 'idle-compact' }, async ($, e) => {
69 const arg = e.args.trim().toLowerCase().replace(/k$/, '')
70 if (arg === 'on' || arg === 'off') enabled = arg === 'on'
71 else if (/^\d+$/.test(arg)) minTokens = Number(arg) * 1000
72 else if (arg) return { text: `Unknown argument "${arg}". Use on, off or a number of thousands of tokens.` }
73 if (!enabled) return { text: 'idle-compact is off.' }
74 const age = await cacheAge($)
75 const tokens = Math.round((await contextTokens($)) / 1000)
76 const last = age === undefined ? 'no reply on record (or already compacted)' : `last reply ${ago(age)} ago`
77 return { text: `idle-compact is on for contexts of ${minTokens / 1000}k tokens or more. Now: ${tokens}k context, ${last}. Last prompt: ${lastPrompt}.` }
78 })
79
80 // The fallback, for when the timer never fired (the computer slept): the cache is already cold, so the
81 // summary call rewrites the context to the cache, about what the prompt would have cost; later turns read only the summary.
82 // The engine refuses a compaction under a prompt.submit hook, so the prompt is dropped, the session
83 // compacts, and the prompt goes back in the box for one Enter.
84 on('prompt.submit', async ($, e, next) => {
85 if (!e.text.startsWith('/')) lastPrompt = `${e.origin.kind}${e.turnId === undefined ? '' : ', mid-turn'}`
86 // typed at the terminal or on a remote surface; notifications, triggers and SDK calls go through
87 const typed = e.origin.kind === 'composer' || e.origin.kind === 'bridge'
88 if (!enabled || e.turnId !== undefined || !typed || e.attachments || e.text.startsWith('/')) return next(e)
89 const age = await cacheAge($)
90 if (age === undefined || age < CACHE_TTL_MS) return next(e)
91 const tokens = await contextTokens($)
92 if (tokens < minTokens) return next(e)
93 cachedAt = undefined
94 $.clock.after(0, async () => {
95 await $.session.compact({ instructions: forPrompt(e.text) }).catch(() => undefined)
96 await $.prompt.fill({ text: e.text })
97 $.ui.toast('idle-compact: compacted. Your prompt is back in the box, press Enter to send it.')
98 })
99 return { drop: `idle-compact: the cache expired, so the ${Math.round(tokens / 1000)}k context is compacted first. Your prompt comes back in the box when it's done.` }
100 }).catch(($, e, next) => next(e))
101
102 on('turn.step', async function* ($, e, next) {
103 const result = yield* next(e)
104 if (e.agentId === undefined && result.usage) {
105 cachedAt = await $.clock.now()
106 knownFor = await $.session.id()
107 }
108 return result
109 })
110}
111