Taming Terminal Costs with Claude Code Idle Compaction

0:00 Ever head off for lunch with a huge refactor open in your terminal, come back an hour later, and your first message feels slow and costly? There's a fix for that. This is The Claude Code Changelog, brought to you by Jellypod AI. I'm Lachlan. And I'm James. Today is Claude Code 2.1.299, released October 14, and the headline is idle compaction in the terminal.

0:25 Here's the exact change. If a conversation is over 200K tokens and sits idle for about 54 minutes, Claude Code compacts it before the one hour prompt cache expires. So when you come back, your next message doesn't reprocess the whole thing. Why 54 minutes? Because the cache lasts an hour. The compaction fires with a few minutes to spare, while the big context is still warm.

0:49 Without it, you'd come back at minute 65, the cache would've expired, and that first message would have to chew through all 200K tokens again. Right, and that's the practical impact. Long sessions are exactly where this bites. Big refactors, heavy debugging, huge tool outputs. Those push you past 200K, and those are also the sessions you walk away from for a meeting or a code review.

1:12 Now the cost of walking away is handled for you. It's the same family of idea as what we covered in the Taming Subagent Bloat episode, with autoCompactWindow in 2.1.296. That one let worker subagents compact early. This one brings compaction thinking to your main interactive session, aimed at the cache clock.

1:35 Now, how do you actually use it? Mostly you don't. It's on by default in the terminal. But there are two knobs. First, the threshold. Set CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS to change that 200K minimum. So if your sessions tend to sit around 120K and you want them covered, export it with a lower number before you launch claude.

1:58 Second, the off switch. In settings.json, set idleCompaction to false. Both of these need version 2.1.290 or later, so run claude dash dash version first if you're not sure what you've got. Worth saying why you might turn it off. Compaction replaces the verbatim conversation with a summary. If you're mid investigation and you need an exact stack trace or exact line numbers later, a summary might not preserve them.

2:28 A habit I'd suggest: before you step away, ask Claude to write the details you need into a notes file in the repo. That's my suggestion, not something from the release notes. Good call. And here's one the changelog does cover. 2.1.299 updated /reload-skills so it says it re-sends the full skill list to Claude, and that's the way to get your skills back after compaction.

2:53 So if Claude seems to have forgotten a custom skill after you return, run that. One more caveat. The changelog doesn't say what happens if you close the terminal or your laptop sleeps during that window. The feature is described as happening while the session sits idle, so I'd assume the session needs to be running, but that's an inference.

3:11 Don't count on it for a closed lid. Fair. Now the smaller bits worth a mention. First, a new env var, CLAUDE_CODE_DISABLE_FILE_MENTIONS. With it set, when you @ mention a file, Claude gets the path to read with its file tools, rather than the contents getting stuffed into the prompt. Handy if you mention big files a lot.

3:36 Second, in agent view, /effort and /fast now set what new sessions start with, and a bare /model, /effort or /fast opens a picker. Third, UserPromptSubmit hooks now run before a skill or custom slash command expands. So a hook that blocks the prompt also stops that command's embedded shell commands. If you use hooks as guardrails, that's a real tightening.

4:00 And two safety and housekeeping ones. The resume command printed at exit now uses the session ID instead of the session name, so nothing in a name can run when you paste that line. And when you @ mention PDFs, their bytes are no longer kept in the session transcript, which helps memory and disk. So the takeaway.

4:22 Update to 2.1.299, check whether your typical session crosses 200K, and if it doesn't, consider lowering CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS. If you rely on exact verbatim history, set idleCompaction to false, or save your notes to a file first. That's the update. Go check your version, and we'll catch you on the next release.