Claude Code コンテキストバックアップフック

問題: 自動圧縮は一度きりのイベントだ。4時間の作業の末、コンテキストが83%に達すると要約処理が動く。次のターンでは、Claude はやったことの大まかな内容しか把握していない。正確なエラー文字列、関数シグネチャ、最初のアプローチを捨てた2つの理由は失われている。

要約は概要は正確に捉える。しかし詳細は生き残らない。

素早い解決策: 使用済みトークンが50Kに達した時点で構造化バックアップを保存し、以降10Kトークンごとに新しいバックアップを書き込む。加えて、残余30%、15%、5%のパーセンテージトリガーが小さなウィンドウに対するセーフネットとして機能する。圧縮が発生したとき、すべてのユーザーリクエスト、すべてのファイル編集、大切にしていた意思決定が記録されたMarkdownファイルが手元に残っている。

StatusLineだけがリアルタイムのトークンデータを持つ

Claude Code のほとんどのフックはコンテキストメトリクスを取得できない。PreToolUse、PostToolUse、Stop—これらはウィンドウがどれだけ埋まっているか知らない。

StatusLine は例外だ。毎ターン context_window.remaining_percentage を含むJSONペイロードを受け取るため、残りのスペースがリアルタイムでわかる。

{
  "session_id": "abc123...",
  "context_window": {
    "remaining_percentage": 35.5,
    "context_window_size": 200000
  }
}

Claude Code でリアルタイムの可視性を提供するメカニズムは他にない。これがなければ、圧縮が発生するまで状況がわからない。

バッファの計算方法

よく引っかかるポイントがある。remaining_percentage フィールドには実際には使えない固定33Kトークンの自動圧縮バッファが含まれている。実装ではパーセンテージではなくトークンベースの計算でこれを考慮する:

const AUTOCOMPACT_BUFFER_TOKENS = 33000;
const autocompactBufferPct = (AUTOCOMPACT_BUFFER_TOKENS / windowSize) * 100;
const freeUntilCompact = Math.max(0, pctRemainTotal - autocompactBufferPct);

200Kウィンドウでは、その33Kバッファは16.5%だ。1Mウィンドウでは3.3%に過ぎない。固定トークン数にすることで、あらゆるウィンドウサイズで計算が正確になる。

デュアルトリガーシステム

自動圧縮はリアクティブだ。ウィンドウの深いところまで到達してから発動し、要約処理中に詳細を捨てる。

バックアップシステムはプロアクティブである必要がある。2つのトリガーレールが並行して動作する:

トークンベースのトリガー（主要）

このレールはウィンドウサイズに関係なく同じように動作する。1Mウィンドウでは最初のバックアップが使用率5%で発動する。200Kウィンドウでは25%で発動する。どちらの場合も早期にカバーできる。

パーセンテージベースのトリガー（セーフネット）

このレールはセーフネットとして機能する。大きなプロンプトインジェクションで始まるセッションなど、トークンレールが見落とす可能性のあるケースをキャッチする。200Kウィンドウでは2つのレールが重なる。1Mウィンドウでは、残り30%に達した時点ですでに670K以上のトークンを使っているため、トークンレールが先に発動する。

3ファイルアーキテクチャ

本番向けバックアップシステムは関心の分離をきれいに行う必要がある。3つのファイルが役割を担う:

.claude/hooks/ContextRecoveryHook/
├── backup-core.mjs        # Shared backup logic
├── statusline-monitor.mjs # Threshold detection + display
└── conv-backup.mjs        # PreCompact hook trigger

backup-core.mjs

このファイルはバックアップの作成に関するすべてを担う:

• トランスクリプト解析: JSONLトランスクリプトファイルを読み込み、ユーザーリクエスト、ファイル変更、タスク、Claudeの重要なレスポンスを抽出する
• Markdownフォーマット: データを読みやすいMarkdownファイルとして構造化する
• ファイル操作: タイムスタンプ付きの番号付きバックアップを保存する
• 状態管理: アクティブなセッションと現在のバックアップパスを追跡する

重要な点: バックアップは生のダンプではなく構造化されたものにする必要がある。Markdownで情報を論理的にグループ化することで、リカバリ時に必要なものを素早く見つけられる。

statusline-monitor.mjs

このファイルはStatusLineを通じて毎ターン実行される。その役割:

1. 使用済みトークンの合計と真の「圧縮までの残り」パーセンテージを計算する
2. トークンベースのトリガーをチェックする（最初に50K、次に10Kごと）
3. セーフネットとしてパーセンテージのしきい値をチェックする（30%、15%、5%）
4. いずれかのトリガーが発動したとき backup-core を呼び出す
5. バックアップパスとともにフォーマットされたステータスを表示する

現在のセッションのバックアップが存在した瞬間からバックアップパスがステータスラインに表示される:

[!] Opus 4.6 | 65k / 1m | 6% used 65,000 | 90% free 900,000 | thinking: On
-> .claude/backups/3-backup-18th-Feb-2026-2-15pm.md

この2行目は50Kトークンを超えた瞬間に表示される。コンテキストが危機的になるまで待たなくてよい。

conv-backup.mjs

PreCompact フックは圧縮が発生する直前に動く。状態をキャプチャする最後のチャンスだ。このファイルは precompact_auto または precompact_manual をトリガー理由として backup-core を呼び出す。

緊急バックアップと考えてほしい。StatusLineベースのしきい値はプロアクティブだ。PreCompact はリアクティブだが、それでもすべてを失うよりはるかにましだ。

設定

2つの settings.json エントリで接続する:

{
  "statusLine": {
    "type": "command",
    "command": "node .claude/hooks/ContextRecoveryHook/statusline-monitor.mjs"
  },
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/ContextRecoveryHook/conv-backup.mjs",
            "async": true
          }
        ]
      }
    ]
  }
}

PreCompact の async: true が重要だ。バックアップが圧縮プロセスを遅延させてはならない。

バックアップファイルの形式

ファイル名には番号が付き、人間が読みやすいタイムスタンプを使用する:

.claude/backups/1-backup-26th-Jan-2026-4-30pm.md
.claude/backups/2-backup-26th-Jan-2026-5-15pm.md
.claude/backups/3-backup-26th-Jan-2026-5-45pm.md

各ファイルの中身は構造化されたサマリーになっている:

# Session Backup
 
**Session ID:** abc123...
**Trigger:** tokens_60k_update
**Context Remaining:** 94.0%
**Generated:** 2026-01-26T17:45:00.000Z
 
## User Requests
 
- Create two blog posts about context management
- Add the new post to blog-structure.ts
- Fix the internal linking
 
## Files Modified
 
- apps/web/src/content/blog/guide/mechanics/context-buffer-management.mdx
- apps/web/src/content/blog/tools/hooks/context-recovery-hook.mdx
- apps/web/src/content/blog/blog-structure.ts
 
## Tasks
 
### Created
 
- **Write Post 1: Context Buffer Management**
- **Write Post 2: Context Recovery Hook**
 
### Completed
 
- 2 tasks completed
 
## Skills Loaded
 
- content-writer

生のトランスクリプトではない。何が起き、何が変わり、何が保留中かを伝える構造化されたサマリーだ。

リカバリのワークフロー

圧縮が発生したとき:

1. ステータスラインにバックアップパスが表示される: 最新のバックアップがどのファイルにあるかが正確にわかる
2. /clear を実行する: 新しいセッションを開始する（圧縮されたコンテキストを継続するよりクリーンだ）
3. バックアップをロードする: Markdownファイルを読み込んでコンテキストを復元する
4. 作業を継続する: Claude は作業していた内容に関する構造化されたコンテキストを持つようになる

圧縮されたコンテキストで作業するということは、Claude がセッションのサマリーを持っているが詳細は失われているということだ。構造化されたバックアップをロードすることで、その詳細が戻ってくる。

/clear を使う理由

圧縮後、2種類のコンテキストが混在する:

1. 圧縮サマリー: 自動生成、情報が失われている、概要だけ
2. ロードしたバックアップ: 構造化、詳細、具体的な内容

両方を残すと混乱が生じる可能性がある。サマリーがバックアップの詳細と矛盾することもある。/clear で新しいセッションを始め、バックアップだけをロードすることで、よりクリーンで信頼性の高いコンテキストが得られる。

状態の追跡

StatusLine と PreCompact は共有の状態ファイルを更新する:

// ~/.claude/claudefast-statusline-state.json
{
  "sessionId": "abc123...",
  "lastFreeUntilCompact": 25.5,
  "lastBackupAtTokens": 60000,
  "currentBackupPath": ".claude/backups/3-backup-18th-Feb-2026-2-15pm.md"
}

これにより StatusLine モニターは次のことを把握できる:

• 追跡しているセッション（セッション変更時に状態をリセットするため）
• 最後のコンテキストパーセンテージ（パーセンテージのしきい値を超えたことを検出するため）
• 最後のバックアップ時のトークン使用数（次の10Kインターバルを計算するため）
• 現在のバックアップの場所（ステータスラインに表示するため）

トランスクリプト解析の詳細

バックアップシステムは Claude Code の JSONL トランスクリプトファイルを解析して意味のあるデータを抽出する。以下がキャプチャする内容だ:

パーサーはノイズを除去する。ツールの結果、システムメッセージ、1文字の入力はフィルタリングされ、セッションのリカバリに実際に重要なものだけが残る。

手動追跡より優れている理由

作業しながら重要なコンテキストを手動でファイルにコピーすることもできる。しかし実際にはしないだろう。実装に集中しているので、ドキュメント化には意識が向かない。

トークンベースのシステムは自動で動く。50Kトークン使用から始まり、意識することなく10Kトークンごとにバックアップが作成される。認知負荷はゼロだ。

そしてバックアップはすでに構造化されている。会話の生のコピー貼り付けではなく、数秒でスキャンできる整理されたセクションになっている。

比較: 自動圧縮 vs しきい値バックアップ

自動圧縮がデフォルトなのは、ほとんどのユーザーがバックアップシステムをセットアップしないからだ。しかし、精度が重要な長時間・複数時間のセッションで生活するなら、トークンベースのバックアップがはるかに優れたリカバリ選択肢を提供してくれる。1Mコンテキストウィンドウでは、1回の圧縮イベントですべてを失う代わりに、セッション全体を通じて数十のスナップショットが記録される。

まとめ

1. StatusLine だけがリアルタイムのコンテキストモニター — 他のフックはトークン数を取得できない
2. トークンベースのトリガーが早期に発動 — 50K使用時に最初のバックアップ、以降10Kごと、ウィンドウサイズに関係なく
3. パーセンテージのしきい値はセーフネット — 30%、15%、5%残りで小さなウィンドウのエッジケースをキャッチ
4. 生のパーセンテージには33Kバッファが含まれる — トークン数を使って真の「圧縮までの残り」を計算する
5. 構造化バックアップが生のダンプより優れている — トランスクリプトを整理されたMarkdownに解析する
6. 3ファイルアーキテクチャ — 検出、バックアップロジック、トリガーの間でクリーンな分離
7. リカバリワークフロー: /clear + ロード — 圧縮されたコンテキストとバックアップを混在させるよりクリーン

関連リソース

• コンテキストバッファ管理 — 33K〜45Kバッファが存在する理由
• Claude Code フックガイド — 12のフック型すべての説明
• コンテキストエンジニアリング — 戦略的なコンテキスト使用法
• セッションライフサイクルフック — セットアップとクリーンアップの自動化