Blog • Claude Code

After a Claude Code terminal session above 200K tokens sits idle for about 54 minutes, how do you turn automatic compaction off in settings JSON?

The Claude Code 2.1.299 note is specific: in the terminal, a conversation above 200K tokens that sits idle for about 54 minutes is compacted before its one-hour prompt cache expires, so the next message does not reprocess the whole history. Compaction replaces the message history with a summary. What stops that replacement is settings.json, not another prompt.

Which fields to keep on a Messages API compaction block is in that API article. Session, permission, and the JSON workflow are in the Claude Code workflow article. This one only covers terminal idle compaction: when it replaces the history, and which two fields in settings.json turn it off or raise the floor.

• The case is a terminal session that is on the one-hour prompt cache.
• The floor is about 200K tokens and about 54 minutes idle. CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS changes only that token floor.
• To keep the history, set idleCompaction to the boolean false. The string false is the wrong shape.
• After you turn it off, the one-hour cache can still expire. The next message may reprocess the whole history. What you keep is a history that a summary does not replace.

When does it actually replace the history?

The 2.1.299 note limits the case to the terminal: a conversation above 200K tokens, idle for about 54 minutes, is compacted before the one-hour prompt cache expires. The same note gives the off switch and the environment variable that changes the token floor, and it says both need 2.1.290 or later. 2.1.302 adds an Idle compaction row in /config, and the notice after a compaction tells you how to turn it off. The changelog is the Claude Code changelog.

The prompt-caching guide says the same event this way: when a terminal session is on the one-hour TTL and has been idle for a long time, Claude Code can compact it shortly before the cache expires. A main conversation on a Claude subscription, inside plan usage, defaults to one hour. On usage credits, an API key, or a cloud provider, the main conversation defaults to five minutes. The idle compaction in that guide is the one-hour case. The setting is idleCompaction set to false, and the version is again 2.1.290 or later. The guide is the prompt-caching guide.

Which two fields do you write in settings.json?

One field turns it off or on. The other only changes the token floor. The value under env is a string, because Claude Code stores environment variables as strings in the settings file. The number 200000 is the wrong shape.

{
  "idleCompaction": false,
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "200000"
  }
}

If you want fewer compactions rather than none, raise the digits in that string. The changelog says the variable changes the 200K-token floor. It does not say the variable changes the about-54-minute wait. From 2.1.302 you can also toggle it in /config without editing the file. A hand edit still needs the boolean, not a string.

Which schema pins the shape of this JSON?

Use JSON Schema to pin the types. idleCompaction must be a boolean. The floor under env must be a string. The schema does not prove that you should turn it off. true is still a valid shape. Keeping the history is an app rule that sends true back to false.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["idleCompaction"],
  "properties": {
    "idleCompaction": { "type": "boolean" },
    "env": {
      "type": "object",
      "properties": {
        "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": { "type": "string" }
      },
      "required": ["CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS"]
    }
  }
}

After compaction, what is still there and what was replaced?

The guide says compaction replaces the message history with a summary, so the conversation-layer cache prefix is no longer the same. The system-prompt layer is reused, unless this resume kept a system prompt that would have changed anyway. Project context is read again from disk. That layer cache-hits only if CLAUDE.md and memory are unchanged since the session started. This is not the compaction block from the Messages API article.

/recap is not the same replacement. It appends the summary as command output, the message history stays, and the cache prefix stays. /rewind truncates back to an earlier turn instead of writing a summary. Idle compaction is the path that replaces the history with a summary.

How is this different from the Messages API compaction article?

How do you check this settings file in JSONNote?

1. 1
   Pick the right operation

   Open JSON Schema. Set Operation to Check with Schema. Paste the settings in the first field and the schema above in the second. idleCompaction may only be a boolean. If the floor is present, it may only be a string.

2. 2
   Reject four bad documents

   Set idleCompaction to the string false, delete idleCompaction, set the floor to the number 200000, or keep env but delete the floor inside it. Each of those fails. The false settings above pass. A pass only means the shape is right.

3. 3
   Diff false against true

   Open JSON Compare Diff. Paste the settings with idleCompaction false in the first field. In the second, change only idleCompaction to true. The floor string can stay the same. Both pass the schema. What stops the automatic history replacement is false, not this shape check.

Common questions

Is this the same as a manual /compact?

No. /compact is what you run yourself between tasks. Idle compaction is the terminal replacing the history with a summary after about 54 minutes without a new message, when the session is above about 200K tokens and on the one-hour cache. Both replace the history. Only the idle path is turned off by idleCompaction in settings.json.

Does an API-key session also compact after 54 minutes?

The guide places idle compaction on a terminal session that is on the one-hour TTL. On usage credits, an API key, or a cloud provider, the main conversation defaults to a five-minute TTL, not one hour. The about-54-minute wait in the changelog is the one that runs before the one-hour cache expires. Do not apply those 54 minutes to the five-minute bucket.

After you turn it off, can the next message still be slow?

Yes. The changelog gives this feature so the next message does not reprocess the whole history. Turning it off only stops a summary from replacing the history. After the cache expires, the next message can still reprocess the uncompacted history. What you keep is the original text.

Is this the same article as the September conversation-compaction one?

No. That one is about the fields the Messages API must store unchanged around compaction so a session can resume. This one is about the Claude Code terminal replacing history after idle time, and how settings.json turns that off. Both are called compaction. The JSON you store is not the same document.

Do tool arguments stay in the compaction summary?

2.1.304 says the compaction summary in the transcript view includes the names of tools called earlier, with the shortcut Ctrl+O. It does not say the full argument JSON stays in the summary. If you still need the arguments, save a copy before compaction and check that copy with a schema.

Summary

In the terminal, a session above about 200K tokens that sits idle for about 54 minutes on the one-hour cache has its history replaced by a summary. CLAUDE.md is read again from disk. Tool names can show up in the transcript summary from 2.1.304. Argument JSON is something you save yourself.

The decision: set idleCompaction to the boolean false to keep the history; if you change the floor, write a string; turning it off does not stop the cache from expiring; neither /recap nor /rewind is this idle replacement.

Back to the blog