tamaratran/fast-jev-compaction

fast-jev-compaction – Claude Code 플러그인 및 npm 라이브러리

무엇을 하는가

• Claude Code를 사용할 때, 모든 도구 사용 (예: Read, Write)과 그 결과가 정확히 저장되기 때문에 세션 기록이 매우 커질 수 있습니다.
• 기본 제공되는 "컴팩션" 기능은 일반적으로 이전 대화를 요약하도록 LLM에 요청하지만, 파일 경로나 정확한 오류 메시지와 같은 중요한 세부 정보가 손실될 수 있습니다.
• fast-jev-compaction은 이 요약을 선택적 제거 프로세스로 대체합니다: Jev 모델(타입세이프 LLM)에 각 도구 호출과 결과가 여전히 필요한지 여부를 묻습니다. 불필요하다고 판단된 항목만 제거되고, 나머지는 원본 그대로 유지됩니다.

작동 방식

1. tool_use_id를 사용해 tool_use와 tool_result를 쌍으로 연결합니다. 첫 번째 메시지와 최신 N개 메시지(설정 가능)는 "핀"되어 절대 수정되지 않습니다.
2. 전체 대화(가장 오래된 것부터)를 포함하는 상태를 구성하지만, 각 결과는 ok, 4213 chars (omitted)와 같은 짧은 플레이스홀더로 대체합니다. 텍스트 메시지의 요약은 전혀 수행하지 않습니다.
3. 점진적으로 도구 입력을 자르고, 긴 텍스트를 약식으로 표현하며, 오래된 메시지를 축소하는 등의 방법으로 maxStateTokens(기본값 25k)의 토큰 예산 내에 상태를 맞춥니다.
4. 핀되지 않은 각 도구 호출에 대해 Jev에 두 가지 yes/no 질문을 보냅니다: 호출을 유지할 것인가? 와 결과를 정확히 유지할 것인가?
5. maxRequestTokens(기본값 30k) 이내에 맞추도록 질문을 필요한 만큼 배치합니다. 요청은 병렬로 실행되며, 답변은 병합됩니다.
6. 임계값(keepThreshold, 기본값 0.5)을 적용합니다:
   • 결과 유지 확률 ≥ 임계값 → 호출과 결과 모두 유지.
   • 그렇지 않지만 호출 유지 확률 ≥ 임계값 → 호출은 유지하고, 결과는 truncateHeadChars(기본값 300)의 문자 수로 자르고 주석을 추가.
   • 그 외 → 둘 다 삭제.
7. 메시지 목록을 재구성하고, 비어 있는 메시지를 제거합니다. 출력에는 호출 없이 결과만 있는 경우가 없습니다.

설치

npm install fast-jev-compaction
export TYPESAFE_API_KEY=…   # 당신의 Typesafe (Jev) 키

기본 사용법 (TypeScript)

import { compactMessages, reductionRatio, type Message } from 'fast-jev-compaction';

const transcript: Message[] = [
  { role: 'user', text: '실패하는 테스트를 수정하세요. src/generated는 수정하지 마세요.', toolUses: [] },
  {
    role: 'assistant',
    text: '',
    toolUses: [{ tool_use_id: 'toolu_1', tool: 'Read', input: { file_path: 'src/a.ts' } }],
  },
  { role: 'user', text: '', toolUses: [], toolResults: [{ tool_use_id: 'toolu_1', text: '…file…' }] },
];

const result = await compactMessages(transcript, { preserveRecentMessages: 4 });
console.log(result.messages, result.decisions, result.stats);
if (reductionRatio(result) < 0.25) {
  // 압축이 충분하지 않음 – 일반 요약으로 백업
}

• compactMessages는 제거된 메시지 목록, 각 호출에 대한 결정, 통계 정보를 반환합니다.
• 고급 사용: 자체 JevAsker를 구현하고(여기서 ask(state, questions) 메서드를 제공), 저수준의 compact(messages, asker, options)를 호출할 수 있습니다.

설정 옵션 (기본값 표시)

옵션	기본값	의미
apiKey	process.env.TYPESAFE_API_KEY	당신의 Typesafe (Jev) API 키
model	jev-latest	쿼리할 Jev 모델
baseUrl	https://api.typesafe.ai/v1/systemone	API 엔드포인트
goal	마지막 3개의 사용자 프롬프트	상태에 포함되는 작업 설명
keepThreshold	0.5	호출/결과 유지에 대한 확률 임계값
preserveRecentMessages	6	최신 메시지는 항상 유지(첫 번째 메시지는 항상 유지)
maxStateTokens	25000	Jev에 전송할 상태의 토큰 예산
maxRequestTokens	30000	각 요청의 토큰 예산(상태 + 질문)
truncateHeadChars	300	삭제된 결과에서 유지할 문자 수

제한 사항

• 삭제되는 것은 오직 도구 호출/결과뿐이며, 일반 사용자/어시스턴트 텍스트는 최종 출력에서 단축되지 않습니다.
• 토큰 수는 정확한 토크나이저가 아니라 문자 길이에서 추정한 근사치입니다.
• 모델의 확률 점수는 보장이 아니며, 어시스턴트는 언제든지 삭제된 도구를 다시 실행할 수 있습니다.
• 전체 상태는 모든 배치 요청과 함께 다시 전송되므로, 매우 긴 기록은 많은 API 호출을 유발할 수 있습니다.

Claude Code 플러그인

• 리포지토리에는 Claude Code 세션에서 이 컴팩션을 자동으로 실행하는 플러그인(hooks/fast-jev.ts)이 포함되어 있습니다.
• Claude Code 마켓플레이스를 통해 설치할 수 있습니다:

  claude plugin marketplace add tamaratran/fast-jev-compaction
  claude plugin install fast-jev-compaction@fast-jev-compaction
  

• 설치 후 /compact 명령어(및 자동 컴팩션)는 Jev를 사용하게 되며, 토스트 메시지로 제거 성공 여부 또는 기본 요약으로 백업 여부가 표시됩니다.

개발 및 데모

• npm test는 네트워크 없이 가짜 Jev 클라이언트로 단위 테스트를 실행합니다.
• demo/JevDemo는 제거 흐름을 시각화하는 작은 SwiftUI macOS 앱입니다. 실제 API를 호출하지 않습니다. 화면 녹화용으로 설계되었습니다.

결론 fast-jev-compaction은 개발자가 중요한 도구 상호작용을 모두 보존하면서도 진정으로 불필요한 기록을 제거할 수 있는 방법을 제공합니다. Claude Code가 일반적으로 수행하는 손실이 있는 요약을 피할 수 있습니다. 이는 일반적인 npm 패키지로 사용할 수 있으며, Claude Code의 1등급 플러그인으로도 사용할 수 있습니다.