Compact Adviser: Claude Code /compact 실행 시점을 알려 주는 모드

Compact Adviser는 한 가지 질문, 즉 Claude Code /compact 실행 시점에 답합니다. 지금 /compact를 실행해야 할까요? 이 모드는 Kun Chen(kunchenguid)이 만들었으며, 하나의 저장소에서 Claude Code, Pi, Codex CLI, Grok용으로 배포됩니다. 이 페이지는 packages/claude-mod에 있는 Claude Code 모드를 다룹니다.

너무 일찍 압축하면 아직 필요한 컨텍스트를 버리게 되고, 너무 늦게 압축하면 매 턴이 긴 대화 기록을 짊어지게 됩니다. 모드는 턴이 끝날 때마다 비용이 적게 드는 로컬 조건 몇 가지를 확인하고, 조건을 통과하면 TypeSafe의 Jev 모델에 대화에 관한 짧은 질문 두 가지를 던집니다. 어시스턴트의 최근 작업 단위가 끝났는가, 그리고 어시스턴트가 직접 작업했는가 아니면 주로 조율만 했는가? 두 답은 하나의 점수로 합쳐집니다. 점수가 기준선을 넘으면 상태 줄이 나타납니다. "work appears completed or recorded. Run /compact to save tokens."

기준선은 컨텍스트가 대부분 비어 있을 때 엄격하고(0.90), 컨텍스트가 Claude Code의 자동 압축 지점에 가까워질수록 0.50 쪽으로 완화됩니다. 아직 여유가 있을 때 잘못된 힌트의 대가가 가장 크기 때문입니다. 자동 모드를 선택하면 모드는 힌트만 주는 대신 그런 체크포인트에서 직접 압축을 실행합니다.

사용자가 직접 마련한 TypeSafe API 키가 필요합니다.

실제 힌트를 보려면 40,000토큰이 넘는 컨텍스트와 TypeSafe 키가 필요한데, 짧은 영상에는 맞지 않습니다. 녹화 영상에서는 모드를 불러온 채 Claude Code를 시작하고, /compact-adviser status(모드, 최솟값, 예산, 키 상태)를 실행한 다음, /compact-adviser 설정 패널을 열어 missing이 표시된 TypeSafe API 키 행으로 이동합니다.

설치 블록의 두 방법 중 하나를 사용하십시오. 둘 다 작성자의 마켓플레이스에서 바로 설치합니다. Claude Code가 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1로 시작되지 않으면 모드는 아무 일도 하지 않으므로, 이 변수와 함께 실행한 뒤 /compact-adviser를 실행해 TypeSafe 키를 추가하십시오.

모든 것은 hooks/register.ts의 turn.complete 훅에서 시작합니다.

on("turn.complete", async ($, e, next) => {
  const result = await next(e);
  if (!(await isActivated($)) || !interactive) return result;
  if (e.agentId !== undefined || e.reason !== "answer" || e.isAborted || !e.answer.trim()) {
    return result;
  }
  try {
    await settle($);
  } catch {
    notice($, "Compact adviser could not inspect this checkpoint; context left unchanged.");
  }
  return result;
});

실제 답변으로 끝난 메인 루프의 턴만 셉니다. 서브에이전트 턴과 중단된 턴은 건너뜁니다. settle은 대화 교환 수를 세고 비용이 적게 드는 관문을 확인합니다. 모드가 꺼져 있지 않을 것, 키가 있을 것, 컨텍스트가 minContextTokens 이상일 것, 쿨다운이나 일시 중지가 없을 것입니다. 통과하면 턴이 지연되지 않도록 $.clock.after(0, …)로 judgeCheckpoint를 예약합니다.

judgeCheckpoint는 $.session.messages()로부터 크기가 제한된 스냅샷을 만들고(lib/snapshot.ts 참고), 대화가 20,000토큰 미만이거나 같은 체크포인트를 이미 판단했다면 요청을 건너뛰며, 그렇지 않으면 $.http.fetch로 https://api.typesafe.ai/v1/systemone에 전송합니다. 요청은 2초 후 시간 초과되며, 오류·시간 초과·잘못된 응답은 절대 '예'로 간주되지 않습니다. 이 경우 모드는 물러나고 대신 토스트를 보여 줍니다. 점수가 기준을 충족하면 힌트 모드는 힌트와 함께 $.ui.status를 호출하고, 자동 모드는 현재 작업, 남은 작업, 다음 단계를 정확히 유지하라는 지시와 함께 $.session.compact를 호출합니다.

사용자가 했든 Claude Code가 했든, 모든 압축은 session.compact 훅을 통해 세션의 쿨다운을 초기화합니다.

/compact-adviser를 실행해 설정 패널을 열거나 하위 명령을 사용하십시오. auto, hint, off는 모드를 바꾸고, threshold 60000은 최소 컨텍스트를 정하며, budget 450000은 기준선이 자동 압축 지점 대신 기준으로 삼을 컨텍스트 예산을 정합니다. snooze는 다음 세 번의 교환을 건너뛰고, dismiss는 현재 힌트를 지우며, status는 현재 상태를 출력합니다. 모드, 최솟값, 예산, 요청 로깅은 /config의 행으로도 있습니다. 판단 프로필(profile 설정의 JSON)로 질문, 점수 가중치, 기준선 일정을 바꿀 수 있습니다.

저희는 무엇이든 실행하기 전에 register.ts, lib/ 아래의 모든 파일, plugin.json, hooks.json, package.json, 테스트 헬퍼를 읽었습니다.

• 네트워크: 모드는 기준을 충족한 체크포인트마다 제3자 서비스인 https://api.typesafe.ai/v1/systemone에 요청 하나를 보내며, 사용자의 키는 Authorization 헤더에 담깁니다. 본문은 최근 대화의 스냅샷으로, 32,000바이트로 제한되며 키 패턴, .env, auth.json, id_rsa/id_ed25519, .pem, .key 파일을 최선의 노력 방식으로 가린 뒤 전송됩니다. TYPESAFE_BASE로 다른 https 주소나 루프백 http 주소를 지정할 수 있습니다. 플러그인 설치는 키가 있을 때 이를 전송하는 데 대한 동의로 간주되므로, 기기 밖으로 나가면 안 되는 작업에서는 모드를 off로 설정하십시오.
• 파일: TYPESAFE_API_KEY를 찾기 위해 세션 폴더의 .env를 읽습니다. 요청 로깅을 켰을 때만 ~/.claude/compact-adviser-requests-<session-id>.jsonl에 쓰며, 이 파일에는 키가 절대 들어가지 않습니다.
• 설정: 패널에서 저장하면 $.config.set을 통해 플러그인 자체의 userConfig 행에 씁니다. 저장된 키는 /config에서 숨겨집니다.
• 압축: 자동 모드에서, 한 번의 확인 대화 상자를 거친 뒤에만 실행됩니다.

설치 스크립트, 번들되거나 압축된 코드는 없으며, TypeSafe 요청 자체 외에 원격 측정(telemetry)도 없습니다.

Claude Code 2.1.291로 검증했습니다. claude plugin validate는 경고 없이 통과하고, claude plugin test는 114개 테스트를 실행해 모두 통과합니다. 작성자는 Claude Code 2.1.274 이상을 요구 사항으로 밝힙니다. 아무 일도 일어나지 않으면 다음을 순서대로 확인하십시오.

• /compact-adviser가 없다면: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS가 정확히 1이 아니거나 COMPACT_ADVISER_DISABLE이 설정되어 있습니다.
• /compact-adviser status에 Key: missing이 표시된다면: 패널, 환경 변수 또는 ./.env에 키를 추가하십시오.
• 명령은 작동하지만 힌트가 나타나지 않는다면: 컨텍스트가 최솟값보다 작거나, 마지막 턴이 확정된 답변으로 끝나지 않았습니다.
• 토스트에 "nonessential network traffic"이 언급된다면: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC이 TypeSafe 요청을 막고 있습니다.
• claude -p 세션은 설계상 항상 비활성입니다.