Compact Adviser：Claude Code で /compact を実行するタイミングがわかる

Compact Adviser は、Claude Code で /compact を実行するタイミングを教えてくれる Mod で、答える問いはひとつ、「今 /compact を実行すべきか？」です。作者は Kun Chen（kunchenguid）で、ひとつのリポジトリから Claude Code、Pi、Codex CLI、Grok 向けに提供されています。このページでは packages/claude-mod にある Claude Code 用の Mod を扱います。

コンパクトが早すぎると、まだ必要なコンテキストを捨ててしまいます。遅すぎると、毎ターン長い履歴を抱えることになります。Mod は各ターンが終わるたびに、手軽なローカルの条件をいくつか確認し、それを通過すると、TypeSafe の Jev モデルに会話について 2 つの短い質問をします。アシスタントの直近の作業単位は完了しているか、そしてアシスタントは作業を自分で行ったのか、それとも主に調整役だったのか。2 つの答えはひとつのスコアにまとめられます。スコアが下限を超えると、"work appears completed or recorded. Run /compact to save tokens." というステータス行が表示されます。

下限は、コンテキストがほとんど空のうちは厳しく（0.90）、コンテキストが Claude Code の自動コンパクトの位置に近づくにつれて 0.50 に向かって緩くなります。まだ余裕があるときほど、誤ったヒントのコストが大きいためです。自動モードを選ぶと、Mod はヒントを出すだけでなく、そうしたチェックポイントで自らコンパクトを実行します。

あなた自身が用意する TypeSafe の API キーが必要です。

実際のヒントには 40,000 トークンを超えるコンテキストと TypeSafe のキーが必要で、短い動画には収まりません。録画では、この Mod を読み込んだ Claude Code を起動し、/compact-adviser status（モード、最小値、予算、キーの状態）を実行してから、/compact-adviser の設定ペインを開いて TypeSafe API キーの行に移動します。そこには missing と表示されています。

インストールブロックのどちらかの方法を使ってください。どちらも作者のマーケットプレイスから直接インストールします。Claude Code を CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 で起動しない限り、Mod はまったく何もしません。この変数を付けて起動してから、/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 秒でタイムアウトし、エラー、タイムアウト、不正な応答が「はい」と見なされることはありません。その場合 Mod は間隔を空け、代わりにトーストを表示します。スコアが条件を満たすと、ヒントモードではヒントとともに $.ui.status を呼び出し、自動モードでは現在の作業、保留中のタスク、次のステップを正確に残すよう指示して $.session.compact を呼び出します。

コンパクトが行われると、あなたによるものでも Claude Code によるものでも、session.compact フックを通じてセッションのクールダウンがリセットされます。

/compact-adviser を実行して設定ペインを開くか、サブコマンドを使ってください。auto、hint、off でモードを切り替えます。threshold 60000 でコンテキストの最小値を設定し、budget 450000 で、下限の計算に自動コンパクトの位置の代わりに使うコンテキスト予算を設定します。snooze は次の 3 回のやり取りをスキップし、dismiss は現在のヒントを消し、status は現在の状態を表示します。モード、最小値、予算、リクエストのログ記録は /config の行としても用意されています。判定プロファイル（profile 設定の JSON）で、質問、スコアの重み、下限のスケジュールを変更できます。

私たちは何かを実行する前に、register.ts、lib/ 以下のすべてのファイル、plugin.json、hooks.json、package.json、テスト用のヘルパーを読みました。

• ネットワーク： Mod は条件を満たしたチェックポイントごとに 1 回、サードパーティのサービスである https://api.typesafe.ai/v1/systemone に、Authorization ヘッダーにあなたのキーを入れてリクエストを送ります。本文は直近の会話のスナップショットで、上限は 32,000 バイトです。キーのパターン、.env、auth.json、id_rsa/id_ed25519、.pem、.key ファイルはベストエフォートで伏せ字にされます。TYPESAFE_BASE で送信先を別の https のベース、またはループバックの http のベースに向けられます。プラグインをインストールすることは、キーがある場合にこの送信を行うことへの同意とみなされるため、マシンの外に出してはいけない作業ではモードをオフにしてください。
• ファイル： TYPESAFE_API_KEY を探すため、セッションフォルダーの .env を読みます。書き込みはリクエストのログ記録をオンにした場合だけで、書き込み先は ~/.claude/compact-adviser-requests-<session-id>.jsonl です。このファイルにキーが含まれることはありません。
• 設定： ペインから保存すると、$.config.set を通じてプラグイン自身の userConfig の行に書き込まれます。保存されたキーは /config には表示されません。
• コンパクト： 自動モードの場合のみ、一度きりの確認ダイアログの後に行われます。

インストールスクリプト、バンドルやミニファイされたコードはなく、TypeSafe へのリクエスト以外のテレメトリーもありません。

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 のセッションは、設計上常に無効です。