Taming Terminal Costs with Claude Code Idle Compaction

Lachlan Reed

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.

James Turner

And I'm James. Today is Claude Code 2.1.299, released October 14, and the headline is idle compaction in the terminal. 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.

Lachlan Reed

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. 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.

James Turner

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. Now the cost of walking away is handled for you.

Lachlan Reed

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.

James Turner

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.

Lachlan Reed

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.

James Turner

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. 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.

Lachlan Reed

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. So if Claude seems to have forgotten a custom skill after you return, run that.

James Turner

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. Don't count on it for a closed lid.

Lachlan Reed

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.

James Turner

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.

Lachlan Reed

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.

James Turner

So the takeaway. 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.

Lachlan Reed

That's the update. Go check your version, and we'll catch you on the next release.