ctx-handoff:Claude Code 長いセッションを楽にするMod

ctx-handoff は CabLate(cablate)による、Claude Code 長いセッション向けのコミュニティModです。数時間続く会話で出てくる雑務をまとめて引き受けます。離席中はごく小さなリクエストを送ってプロンプトキャッシュの期限切れを防ぎ、繰り返した指示をプロジェクトごとのノートにして新しい会話へ読み込み、Claude が失敗したツールを再試行したときや、確認せずに「完了」と言ったときに一言促します。

大きな機能が 2 つありますが、こちらは自動ではありません。任意の引き継ぎは、コンテキストがしきい値に達すると作業の要約を書き、会話をクリアして新しい会話で続けるもので、既定ではオフです。ガードは、繰り返したルールから Mod が下書きするツール呼び出しのチェックで、承認するまで適用されません。入力欄の上のパネル(/handoff panel)には、ガード、メモリ、ルール、直近のノート更新、すべての設定が並びます。

作者の README は、Claude のサブスクリプションと大きなコンテキストでの長いセッションを想定しています。API キー、Bedrock、Vertex ではキャッシュが 5 分しか持たないため、作者は /handoff refresh off を勧めています。

録画では、小さなデモプロジェクトでこの Mod を読み込んだ Claude Code を起動します。フッターにはすぐ ctx-handoff: 30 more messages until notes update と表示されます。次のバックグラウンドのノート更新までのカウントダウンです。続いて /handoff guard を実行すると、Guards: none と、ガードが下書きされる条件が表示されます。/handoff refresh では Currently on. Usage: /handoff refresh on|off と表示されます。録画中にモデルへのリクエストは発生せず、パネルも開きません。パネルにはノートファイルのフルパスが表示されるためです。

インストールブロックのいずれかの方法を使ってください。どれも作者自身のマーケットプレイスから直接インストールします。新しいセッションを開始して /handoff を実行します。セッション開始後にフッターのカウントダウンが表示されます。

すべての機能は 1 つのモジュール hooks/register.ts から登録されます。ターンが終わるたびにアイドルタイマーが再開されます。タイマーが作動し、コンテキストが min_tokens を超えていれば、キャッシュされた会話を読むための最小の fork リクエストを送り、次の更新を予約します。次はそのスケジュール関数で、hooks/register.ts からの抜粋です。

async function schedule($: EngineInterface, delay = cfg.idleMs) {
  rt.idle?.cancel()
  if (await awayPaused($)) { rt.idle = undefined; await update($, idleState, () => null); return }
  rt.idle = $.clock.after(delay, () => void onIdle($))
  const due = (await $.clock.now()) + delay
  await update($, idleState, () => ({ due, refreshes: rt.refreshes }))
}

既定のアイドル時間は 50 分、更新は最大 3 回で、その後はクリアせずに離席用の引き継ぎを保存します。ユーザーメッセージ 30 件ごと、または引き継ぎの前に、履歴を持たない別のリクエストが、会話の新しい部分だけをノート用モデル(claude-sonnet-5-5、低い推論強度)に送ります。返ってきた JSON のアクションはコードで検証され、ユーザーの引用は実際のメッセージの中に見つかる必要があり、秘密情報のように見える行は書き込み前に捨てられます。ノートは prompt.context で新しい会話に注入されます。

この Mod は userConfig を宣言していません。設定はパネルの設定タブ(/handoff panel を開いてキー 5)にあり、settings.json の pluginConfigs["ctx-handoff@<marketplace>"].options も読みます。両方ある場合はパネルの値が優先されます。設定には auto_handoff(既定はオフ)、threshold(600000 トークン)、idle_minutes(50)、max_refresh(3)、min_tokens(30000)、distill_every(30)、notes_model、retry_nudge、done_check、reply_language、language があります。残りはスラッシュコマンドで操作します。/handoff now、dry、distill on|off、refresh on|off、away pause|resume、guard、resume、continue、resend です。

マニフェスト、hooks/hooks.json、hooks/register.ts の全体、設定、ノート、引き継ぎ、ガード、ループ、言語、プロモート、整理プロンプトの各モジュールを読みました。残りのファイルは主に i18n の文字列、パネルの表示、小さな記録用ヘルパーで、1 行ずつ読む代わりに検索で副作用がないか確認しました。リポジトリには package.json、インストールスクリプト、バイナリ、minify されたコードはありません。tools/ は作者向けのスクリプトで、プラグインは読み込まず、私たちも実行していません。隠れた Unicode 文字はありません。

知っておくべき点:

• モデルへのリクエストはあるが、他のネットワークアクセスはない。 fetch、プロセス呼び出し、ネットワークのコードはありません。$.model.fork と $.model.complete を呼び、Claude の利用枠を使います。会話の内容は、ノートや引き継ぎの要約のために、会話そのものと同じ形で送られます。
• 自分のストアの外に書き込む。 $.fs.write が <claude 設定ディレクトリ>/projects/<ワークスペース>/memory/ctx-handoff.md を作成・更新し、パネルでノートを削除する前に .ctx-handoff-backup/ へバックアップを書きます。バックグラウンドのノート更新は既定でオンですが、ホームフォルダで開始したセッションでは行われません。settings.json、シェルのファイル、LaunchAgents には触れず、HOME、USERPROFILE、CLAUDE_CONFIG_DIR を読みます。
• モデルにテキストを注入する。 prompt.context は、ノート、任意の進捗メモ、ガードの質問を [ctx-handoff] のタグ付きで新しい会話に追加します。ツール結果にリマインダーが付くこともあります。git リポジトリでルールが 3 回繰り返されると、注入されるテキストは、確認なしでそれをリポジトリ(CLAUDE.md、.claude/skills、フック)に書くよう Claude に指示します。ただしコミットはさせません。ノートはモデルが書いた会話の要約なので、ときどきファイルを確認してください。
• ゲートするフック。 tool.call が呼び出しを拒否するのは、承認済みのガードの場合だけです。classic.Stop は、ファイルを編集したのにチェックを実行していない場合、ターンごとに 1 回だけ「完了」の回答を止めます(done_check、既定でオン)。prompt.submit は、引き継ぎの実行中あなたのメッセージを保留します。自動引き継ぎをオンにすると、Mod 自身が /clear を実行して要約を送信します。
• デーモンもテレメトリもない。 タイマーは Claude Code のプロセス内にあるだけで、利用統計はプラグインのストアに残ります。
• 管理された環境。 claude plugin validate によると、組織が Claude Code を管理している環境では、ユーザーがインストールしたプラグインの prompt.context と classic.Stop のフックは動きません。
• ライセンス。 MIT で、LICENSE ファイルがあります。

claude plugin validate はエラーを報告しませんでした。警告は、リポジトリ直下の CLAUDE.md がプラグインのコンテキストとして読み込まれない、という 1 件だけです。作者の 15 ファイル・290 件のテストは Claude Code 2.1.303 ですべて通りました。

macOS 上の Claude Code 2.1.303 で確認しました(validate、テスト、録画)。作者の README は 2.1.287 以降を必要としています。/handoff が反応しない場合は次を確認してください。

• claude --version が 2.1.287 以降で、インストール後に新しいセッションを始めた。
• 別の /handoff コマンドがすでにある場合、Mod は代わりに /ctx-handoff を登録します。
• ノート更新がオフのとき、またはホームフォルダで Claude Code を起動したときは、フッターのカウントダウンは出ません。
• キャッシュ更新はキャッシュが 1 時間持つ環境でだけ役に立つので、API キーでは /handoff refresh off でオフにしてください。
• /handoff を実行すると、直近の失敗やノートファイルのパスを含む現在の状態が見られます。