tamaratran/fast-jev-compaction

fast-jev-compaction – Claude Code プラグインおよび npm ライブラリ

何をするか

• Claude Code を使用する際、すべての ツール使用（例：Read、Write）とその結果が正確に保存されるため、セッション履歴が非常に大きくなることがあります。
• 通常の組み込み「コンパクション」機能は、古いターンを 要約 するように LLM に依頼しますが、ファイルパスや正確なエラーメッセージなどの重要な詳細が失われる可能性があります。
• fast-jev-compaction はその要約を 選択的削除 プロセスに置き換えます：Jev モデル（Typesafe LLM）に、各ツール呼び出しと結果がまだ必要かどうかを尋ねます。不要と判断されたものだけが削除され、それ以外は元のまま保持されます。

動作方法

1. tool_use_id で tool_use と tool_result をペアリングします。最初のメッセージと最新の N メッセージ（設定可能）は「ピン」され、一切変更されません。
2. 全ての会話（最も古いものから）を含む 状態 を構築しますが、各結果は ok, 4213 chars (omitted) のような短いプレースホルダに置き換えます。テキストメッセージの要約は一切行いません。
3. トークン予算（maxStateTokens、デフォルト 25k）に収まるように、ツール入力の段階的削減、長文の省略、古いメッセージの統合などにより状態を調整します。
4. ピン留めされていない各ツール呼び出しに対して、Jev に 2 つの 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 の第一級プラグインとしても利用可能です。