블로그 • Claude Code

Claude Code 터미널에서 20만 token을 넘긴 세션이 약 54분 유휴 상태가 된 뒤, 설정 JSON으로 자동 압축을 어떻게 끄나?

Claude Code 2.1.299 업데이트 설명은 구체적이다. 터미널에서 20만 token을 넘긴 대화가 약 54분 유휴이면 한 시간 프롬프트 캐시가 만료되기 전에 압축되어, 다음 메시지가 이력 전체를 다시 처리하지 않아도 된다. 압축은 메시지 이력을 요약으로 바꾼다. 이 교체를 멈추는 것은 settings.json이지, 프롬프트를 하나 더 보내는 것이 아니다.

Messages API의 compaction 블록에 남길 필드는 그 API 글. 세션, 권한, JSON 작업 흐름은 Claude Code 작업 흐름 글. 이 글은 터미널 유휴 압축만 쓴다. 언제 이력을 바꾸는지, settings.json의 어느 두 필드로 끄거나 기준을 올리는지.

• 대상은 터미널 세션이고, 그때 한 시간 프롬프트 캐시를 쓰는 경우다.
• 기준은 약 20만 token, 유휴는 약 54분이다. CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS는 이 token 하한만 바꾼다.
• 원문을 남기려면 idleCompaction을 불리언 false로 둔다. 문자열 false는 모양이 틀리다.
• 끈 뒤에도 한 시간 캐시는 만료될 수 있다. 다음 메시지는 이력 전체를 다시 처리할 수 있다. 남는 것은 요약으로 바뀌지 않는 이력이다.

어떤 조건에서 이력이 바뀌나?

2.1.299 업데이트 설명은 범위를 터미널로 한정한다. 20만 token을 넘긴 대화가 약 54분 유휴이면 한 시간 프롬프트 캐시가 만료되기 전에 압축된다. 같은 설명에 끄는 방법과 token 하한을 바꾸는 환경 변수가 있고, 둘 다 2.1.290 이상이 필요하다고 적혀 있다. 2.1.302는 /config에 Idle compaction 한 줄을 더하고, 압축 뒤의 안내도 끄는 방법을 알려 준다. 원문은 Claude Code 업데이트 설명.

프롬프트 캐시 문서는 같은 일을 이렇게 적는다. 터미널 세션이 한 시간 TTL 위에 있고 오래 유휴이면, Claude Code는 캐시가 만료되기 직전에 압축할 수 있다. 구독 플랜 안의 주 대화는 기본이 한 시간이다. 사용량 크레딧, API key, 클라우드 제공자에서는 주 대화의 기본이 5분이다. 그 문서의 유휴 압축은 한 시간인 경우를 말한다. 끄는 설정 이름은 idleCompaction, 값은 false, 버전도 2.1.290 이상이다. 문서는 프롬프트 캐시 문서.

settings.json에는 어느 둘을 적나?

한 필드는 켜고 끄기를 정하고, 다른 필드는 token 하한만 바꾼다. env의 값은 문자열이다. Claude Code는 설정 파일의 환경 변수를 문자열로 둔다. 200000을 숫자로 쓰면 모양이 틀리다.

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

압축을 줄이고 싶을 뿐 끄고 싶지 않다면 그 문자열의 숫자를 올린다. 업데이트 설명은 이 변수가 20만 token 하한을 바꾼다고 하고, 약 54분을 바꾼다고는 적지 않는다. 2.1.302부터는 /config에서도 전환할 수 있어 파일을 직접 고치지 않아도 된다. 직접 고칠 때는 여전히 불리언이지 문자열이 아니다.

이 JSON의 모양은 어떤 Schema로 고정하나?

JSON Schema로 타입을 고정한다. idleCompaction은 불리언이어야 한다. env의 하한은 문자열이어야 한다. Schema는 꺼야 하는지를 증명하지 않는다. true의 모양은 맞다. 이력을 남기는 것은 앱 규칙이고, true를 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"]
    }
  }
}

압축 뒤에 무엇이 남고, 무엇이 바뀌었나?

문서는 이렇게 적는다. 압축은 메시지 이력을 요약으로 바꾸므로, 대화 층의 캐시 접두사는 더 이상 같지 않다. 시스템 프롬프트 층은 계속 쓰인다. 이번 재개가 원래 바뀔 시스템 프롬프트를 유지한 경우는 예외다. 프로젝트 맥락은 디스크에서 다시 읽는다. CLAUDE.md와 메모리가 세션 시작 이후 바뀌지 않았을 때만 그 층이 캐시에 맞는다. 이것은 Messages API 글의 compaction 블록이 아니다.

/recap은 같은 교체가 아니다. 요약을 명령 출력으로 덧붙이므로 메시지 이력도 캐시 접두사도 남는다. /rewind는 더 이른 턴으로 자르는 것이지 요약을 쓰는 것이 아니다. 이력을 요약으로 바꾸는 것은 유휴 압축이다.

Messages API 압축 글과 무엇이 다른가?

JSONNote에서 이 설정을 어떻게 확인하나?

1. 1
   동작을 고른다

   JSON Schema를 연다. 작동하다 를 Schema로 확인하세요 로 바꾼다. 첫 칸에 설정, 둘째 칸에 위 Schema를 붙인다. idleCompaction은 불리언만. 하한을 적는다면 문자열만.

2. 2
   나쁜 데이터 넷을 부딪힌다

   idleCompaction을 문자열 false로 하거나, idleCompaction을 지우거나, 하한을 숫자 200000으로 하거나, env는 두고 안의 하한만 지운다. 이 넷은 실패한다. 위의 false 설정은 통과한다. 통과는 모양이 맞다는 뜻만 가진다.

3. 3
   false와 true를 비교한다

   JSON 비교 Diff. 첫 칸에 idleCompaction이 false인 설정을 붙인다. 둘째 칸은 idleCompaction만 true로 바꾼다. 하한 문자열은 같아도 된다. 둘 다 Schema는 통과한다. 이력의 자동 교체를 막는 것은 false이지, 이번 모양 확인이 아니다.

자주 묻는 질문

수동 /compact와 같은 한 번인가?

같은 한 번이 아니다. /compact는 작업 사이에 직접 실행한다. 유휴 압축은 새 메시지가 약 54분 없고, 세션이 약 20만 token을 넘고, 한 시간 캐시 위에 있을 때 터미널이 스스로 요약으로 바꾸는 것이다. 둘 다 이력을 바꾼다. settings.json의 idleCompaction으로 끄는 것은 유휴 쪽뿐이다.

API key 세션도 54분 뒤에 압축되나?

문서는 유휴 압축을 한 시간 TTL의 터미널 세션에 둔다. 사용량 크레딧, API key, 클라우드 제공자의 주 대화는 기본 TTL이 5분이지 한 시간이 아니다. 업데이트 설명의 약 54분은 한 시간 캐시가 만료되기 전에 도는 것이다. 5분 구간에 이 54분을 적용하지 않는다.

끈 뒤에도 다음 말은 느릴 수 있나?

느려질 수 있다. 업데이트 설명이 이 기능을 둔 이유는 다음 메시지가 이력 전체를 다시 처리하지 않게 하려는 것이다. 끄는 것은 요약이 이력을 바꾸는 것만 멈춘다. 캐시가 만료된 뒤 다음 메시지는 압축되지 않은 이력을 다시 처리할 수 있다. 남는 것은 원문이다.

9월 Conversation Compaction 글과 같은 글인가?

같은 글이 아니다. 그 글은 Messages API가 압축 전후에 그대로 저장해야 세션을 되돌릴 수 있는 필드를 쓴다. 이 글은 Claude Code 터미널이 유휴 뒤에 이력을 바꾸는 것과 settings.json으로 끄는 방법을 쓴다. 둘 다 압축이라고 불린다. 저장하는 JSON은 같은 문서가 아니다.

도구 인자는 압축 요약에 남나?

2.1.304가 적는 것은 전사 보기의 압축 요약에 앞서 호출한 도구의 이름이 붙는다는 것이다. 단축키는 Ctrl+O다. 인자 JSON 전체가 요약에 남는다고는 적지 않는다. 인자가 아직 필요하면 압축 전에 사본을 저장하고, 그 사본을 Schema로 확인한다.

정리

터미널에서 약 20만 token을 넘긴 세션이 한 시간 캐시 위에서 약 54분 유휴이면 이력이 요약으로 바뀐다. CLAUDE.md는 디스크에서 다시 읽힌다. 도구 이름은 2.1.304부터 전사 요약에 나올 수 있다. 인자 JSON은 직접 저장한다.

결론: 이력을 남기려면 idleCompaction을 불리언 false로 둔다. 하한을 바꾸려면 문자열로 쓴다. 꺼도 캐시 만료는 멈추지 않는다. /recap도 /rewind도 이번 유휴 교체가 아니다.

블로그로 돌아가기