Build This Now
Build This Now
キーボードショートカットステータスラインガイド
フックガイドClaude Code クロスプラットフォームフックClaude Code セットアップフックストップフック自己検証する Claude Code エージェントClaude Code セッションフックClaude Code コンテキストバックアップフックスキルアクティベーションフックClaude Code パーミッションフックClaude CodeのMCPツールフックCommands to Skills
Skills, Subagents, HooksSubagent Sweet SpotCLAUDE.md Best PracticesFix Context Limit
speedy_devvkoen_salo
Blog/Toolkit/Hooks/Context Backup Hooks

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

StatusLineを活用したClaude Codeのコンテキストバックアップフック。10Kトークンごとに構造化されたスナップショットを書き込み、自動圧縮によってエラー文字列・関数シグネチャ・判断内容が失われるのを防ぐ。

設定をやめて、構築を始めよう。

AIオーケストレーション付きSaaSビルダーテンプレート。

企業向けに構築している実績を見る →
speedy_devvWritten by speedy_devvPublished Jan 21, 2026Toolkit hubHooks index

問題: 自動圧縮は一度きりのイベントだ。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つのトリガーレールが並行して動作する:

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

トリガー発動タイミング目的
50Kトークン累計50Kトークン使用後最初のバックアップ、早期キャプチャ
10Kごと60K、70K、80K、90K、100K...定期更新

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

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

しきい値発動タイミング目的
30%圧縮まで約60Kトークン残り追加チェックポイント
15%圧縮まで約30Kトークン残り危機的な状況
5%圧縮まで約10Kトークン残り圧縮前の最後のチャンス
5%以下コンテキストが減少するたびに継続的バックアップモード

このレールはセーフネットとして機能する。大きなプロンプトインジェクションで始まるセッションなど、トークンレールが見落とす可能性のあるケースをキャッチする。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 トランスクリプトファイルを解析して意味のあるデータを抽出する。以下がキャプチャする内容だ:

データ種別抽出方法
ユーザーリクエストtype === "user" のメッセージ
変更されたファイルfile_path を持つ Write/Edit ツール呼び出し
作成されたタスクTaskCreate ツール呼び出し
完了したタスクstatus === "completed" の TaskUpdate
サブエージェント呼び出しTask ツールの呼び出し
ロードされたスキルSkill ツールの呼び出し
MCPツール使用mcp__ で始まるツール名
ビルド/テスト実行build/test/npm/pnpm を含む Bash コマンド

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

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

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

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

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

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

項目自動圧縮しきい値バックアップ + /clear
発動タイミング約83.5%使用時50Kトークン、以降10Kごと
保存される内容情報が失われる要約詳細を含む構造化Markdown
コントロールなし（ハードコード）設定可能なトークン + パーセンテージのしきい値
リカバリ要約で継続特定のバックアップファイルをロード
詳細の保持要約に収まるものだけバックアップ内のすべて

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

まとめ

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

関連リソース

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

Continue in Hooks

  • Slash Commands Are Now Skills: Migrating Commands to Skills
    Claude Code slash commands and skills now do the same thing. Here is how to migrate .claude/commands to .claude/skills and why it pays off.
  • Claude Code セットアップフック
    スクリプト、エージェント、ドキュメントをClaude Codeのセットアップフックに組み合わせる方法。1つのコマンドで決定論的スクリプトを実行し、診断エージェントに出力を渡し、自動更新されるドキュメントを記録する。
  • Claude Code クロスプラットフォームフック
    Claude Codeのクロスプラットフォームフック: .cmd・.sh・.ps1のラッパーを捨て、nodeを直接呼び出すことで、1つの.mjsファイルがmacOS・Linux・Windowsで動く方法。
  • フックガイド
    Claude Code フックの基礎から実践まで: 終了コード、JSON出力、非同期コマンド、HTTPエンドポイント、PreToolUseとPostToolUseのマッチャー、本番環境パターン。
  • Claude CodeのMCPツールフック
    type: mcp_toolを使ってClaude CodeのフックからMCPサーバーのツールを直接呼び出す方法。スキーマ、変数展開の構文、ユースケース、本番パターンまで解説します。
  • Claude Code パーミッションフック
    3階層の Claude Code パーミッションフックをインストールする: 安全な呼び出しは即時許可、危険な呼び出しは即時拒否、グレーゾーンは LLM チェック。スキップフラグ不要。

More from Toolkit

  • CLAUDE.md, Skills, Subagents, Hooks: When to Use Which
    Claude Code skills vs subagents vs hooks vs CLAUDE.md: a plain mental model for picking the right primitive, with token costs and examples.
  • Claude Code Subagents: The 3 to 5 Agent Sweet Spot
    Claude code subagents work best at 3-5 concurrent agents. Here is why that ceiling exists, how to set them up, and what to use past it.
  • CLAUDE.md Best Practices: The File That Makes Claude Code Reliable
    CLAUDE.md best practices: keep it under 200 lines, write it by hand, and use hooks when you need real enforcement, not advice.
  • How to Fix Claude Code Running Out of Context
    Claude Code running out of context is a session design problem. Fix it with /compact, lean CLAUDE.md, skills, and subagents, not a bigger window.

設定をやめて、構築を始めよう。

AIオーケストレーション付きSaaSビルダーテンプレート。

企業向けに構築している実績を見る →

Claude Code セッションフック

4 つの Claude Code セッションライフサイクルフック: オンデマンドで init を実行し、SessionStart でプロジェクトコンテキストを注入し、トランスクリプトをバックアップし、SessionEnd 終了時にログクリーンアップを行う。

スキルアクティベーションフック

UserPromptSubmitフックがメッセージを解析し、キーワードにマッチしてスキルアクティベーションのヒントを追加することで、Claude Codeが正しいスキルを読み込み忘れることをなくします。

On this page

StatusLineだけがリアルタイムのトークンデータを持つ
バッファの計算方法
デュアルトリガーシステム
トークンベースのトリガー（主要）
パーセンテージベースのトリガー（セーフネット）
3ファイルアーキテクチャ
backup-core.mjs
statusline-monitor.mjs
conv-backup.mjs
設定
バックアップファイルの形式
リカバリのワークフロー
/clear を使う理由
状態の追跡
トランスクリプト解析の詳細
手動追跡より優れている理由
比較: 自動圧縮 vs しきい値バックアップ
まとめ
関連リソース

設定をやめて、構築を始めよう。

AIオーケストレーション付きSaaSビルダーテンプレート。

企業向けに構築している実績を見る →