Claude Code のセッション一覧を「閉じたら自動で消える」ようにする

この指示書が解く問題

Claude Code を使い込むと、サイドバーのセッション一覧が数十件に膨れて目的のものを探せなくなる。 利用者はたいてい /clear を押して片付けようとするが、/clear は削除コマンドではない。 「会話コンテキストをリセットして新しいセッションを開始する」機能なので、一覧からは何も消えず、 むしろ押すたびにメタ行だけを持つ空セッションが1件増える。 その結果「押しても消えない → 押したか分からない → また押す」が無限に続く。

このMDは、セッションを閉じたら一覧から自動的に消える状態を作る手順である。

前提知識（ここを外すと必ずハマる）

1. 一覧は ~/.claude/projects/<projectId>/<sessionId>.jsonl の実体から作られる。 jsonl を別ディレクトリへ move すれば一覧から消える。削除する必要はない（復元可能にしておくこと）。
2. エディタ拡張の「ゴミ箱」はファイルを消さない。 拡張の状態DBに「非表示ID」を追加するだけで、 実体は残り続ける。しかもその追加は read-modify-write なので、複数ウィンドウを開いていると lost update が起きて削除済みが一覧に復活することがある。状態DBへの書き込みは避け、read-only で観測に留める。
3. モデル（AI）は自分の session_id を知らない。 hook だけが session_id を受け取れる。 つまり「今のセッションを閉じる」を実装するには、hook が session_id をファイルへ書き出す経路が必須。
4. タブを開いたままだと拡張が jsonl を触り続け、mtime が更新され続ける。 「最終更新から N 秒経過したら退避」という判定は、この事実を織り込まないと永久に発火しない。

構成

3つの部品で作る。

部品	役割
current-session.mjs（UserPromptSubmit hook）	発言のたびに ~/.claude/current-sessions/<id>.json へ {sessionId, cwd, at} を記録
close-session.mjs（CLI）	「閉じた」台帳 ~/.claude/closed-sessions.json に ID を積む
purge-sessions.py（常駐ウォッチャー）	30秒ごとに台帳を見て、条件を満たした jsonl を退避ディレクトリへ move

セッション終了手順（スキルやスラッシュコマンド）の最後に close-session.mjs を呼ぶだけで、 数十秒後に一覧から消える。

実装のポイント

退避の判定は「経路ごとに待ち時間を変える」

明示的に閉じた（closed 台帳）      → 45秒で退避。利用者が閉じると宣言済みなので短くてよい
利用者が削除操作をした かつ 空     → 90秒で退避。実発言も応答も0件で失う情報が無い
利用者が削除操作をした かつ 中身有 → 600秒。稼働中の可能性があるので慎重に

「削除操作済み」を一律に長い閾値へ入れてはいけない。 空セッションを長い閾値に入れると、タブが開いている限り mtime が更新され続けて永久に消えない （実測でこれが「ゴミ箱を押しても消えない」の真因だった）。

空セッションの判定

user / assistant の中身のあるメッセージが1件でもあれば空ではない。 ただし <command-name> <command-message> <local-command-caveat> のような コマンド記録は発言に数えない（/clear のスタブがこれに該当するため）。 ファイルサイズに上限（例: 200KB）を設けて、大きいファイルは読まずに除外すると I/O と誤判定を防げる。

稼働中セッションを絶対に退避しない

current-sessions/ の各記録を読み、at が十分新しいものを集合として保護する。 単一のグローバルファイルに「現在のセッション」を1件だけ持つ設計にしてはいけない。 利用者が複数タブを開いていると、最後に発言したセッションで上書きされ、 ①保護対象が1本しか残らない ②「今のセッションを閉じる」が別のセッションを閉じる、という二重の事故になる。

引数なしで閉じるときは、迷ったら止める

close-session を引数なしで呼んだとき、直近60秒に2件以上のセッションが動いていたら 台帳に積まずにエラー終了し、--session <id> の明示を促す。 間違ったセッションを閉じるより、止まる方が安全。

session_id をモデルに知らせるには、hook の標準出力を使う。ただし毎回出すと文脈を汚しトークンが増えるので、 プロンプトが終了コマンドを含むときだけ1行出す。

if (prompt.includes("session-close")) {
  console.log(`[session] このセッションのIDは ${sessionId}。--session ${sessionId} を付けて呼べ。`);
}

常駐ウォッチャーの作法

• heartbeat ファイルに PID を書き、二重起動を防ぐ（stale 判定は 90 秒程度）
• スクリプトを更新したらウォッチャーの再起動が必須。実行中プロセスは起動時のコードを保持するので、 ファイルを書き換えただけでは反映されない（PID kill → heartbeat 削除 → 再起動）
• OS ごとに差がある箇所は分岐する。プロセスの detach は Windows が creationflags、 POSIX が start_new_session=True で、取り違えると例外になる

チーム全体へ配る場合

• 各PCの設定ディレクトリへコピーした「凍結コピー」を hook に登録してはいけない。 凍結コピーは自分自身を更新しないので、以後の改修がそのPCへ永久に届かない。 正本は配布用リポジトリに置き、hook はリポジトリ内のパスを指すよう登録する。 既に凍結コピーが登録されている環境のために、登録スクリプトに「旧パス→リポジトリのパス」への 張り替え処理を必ず入れる。
• 張り替え処理は冪等にすること。「既に目的のコマンドなら書き換えず、変更カウントも増やさない」。 増やすと差分ゼロでも設定ファイルが毎回書き直され、バックアップが全PCで日々積み上がる。
• ランタイム（例: python）を hook から直接叩かない。薄いランチャーを1枚挟むと、 python3 / python / py の差と、登録スクリプト側の拡張子前提の両方を吸収できる。

検証のしかた（本番のセッションで試さない）

一時ディレクトリを偽のホームとして作り、環境変数のホームを差し替えて実行する。 次の4種を仕込んで、退避される/されないを assert する。

1. 閉じた台帳に載せた空セッション（古い mtime）→ 退避される
2. 削除操作済みの空セッション（古い mtime）→ 退避される
3. 削除操作済みだが中身のあるセッション（新しい mtime）→ 残る
4. 稼働中として記録されているセッション → 空でも 残る

加えて「元ファイルは1本も消えておらず、必ず退避先に実在する」を assert する。 これが削除していないことの証明になる。CI に載せるなら Linux でも動くことを確認しておく。

安全側の原則

• jsonl は削除しない。必ず move。退避先から戻せる状態を保つ
• 拡張の状態DBは read-only。書き込むと他ウィンドウとの lost update を持ち込む
• 無人で回る処理なので、失敗が無限リトライにならないようにする （台帳から取り除く処理は、必ず読み直してから差し引く。読み込み時のスナップショットで 丸ごと書き戻すと、並行して追記された ID を失う）