claude-code-history-files-finder

Claude Code 履歴ファイル検索ツール

アクティブなホームと、明示的に登録された長期アーカイブに保存されている Claude Code セッション履歴から、コンテンツを検索して復元します。

機能

• ファイル履歴のスナップショットから、削除または失われたファイルの正確にキャプチャされたバイト列を復元します。元の Write 呼び出し後に変更されたファイルも対象です
• 会話履歴全体から特定のコードやコンテンツを検索します
• 過去のセッションにおけるファイル変更を分析します
• ツールの使用状況やファイル操作を経時的に追跡します
• 特定のキーワードやトピックを含むセッションを見つけます

完全性の不変条件

通常の履歴検索では、次の両方のソース種別を対象にする必要があります。

1. 自動検出されたアクティブなホーム（~/.claude、プロファイルのホーム、現在の CLAUDE_CONFIG_DIR）、および
2. ~/.claude/history-sources.json に登録されたすべてのアーカイブ。

コマンドの出力で登録済みアーカイブが検索されたことを確認できない限り、セッション、トピック、ファイル、操作が存在しないと結論づけないでください。必須のアーカイブが利用できない場合は、重大な設定エラーです。--home と --main-only は、アーカイブレジストリを意図的に迂回する、厳密な診断用スコープです。どちらかのフラグによる結果を、履歴全体に対する不在の根拠にすることはできません。

完全なソースセットは必要ですが、それだけでは十分ではありません。すべてのソースを対象にしていても、さらに次の3つの失敗モードによって誤って「見つからない」と判断することがあります。該当がない場合、スクリプトはそれぞれの対象範囲を広げる方法を自動的に表示します。

1. プロジェクトの推測違い。 あるプロジェクトを検索したものの、会話は別のプロジェクトで行われていました。対象範囲を広げる方法：--all-projects を指定すると、すべてのプロジェクトを一度に検索します。
2. ツールの違い。 会話は Codex または Kimi CLI で行われていました。これらのロールアウト／ワイヤーログは別のストアに保存されており、Claude のレジストリでは対象になりません。対象範囲を広げる方法：--codex と --kimi（どちらもオプトイン。両方のツールでプロジェクトを開発していた場合は両方を指定します）。
3. 表現のずれ。 覚えている引用が句読点や数語の違いで実際の表現と異なり、完全一致の検索で見つかりません。対象範囲を広げる方法：特徴的な短い部分文字列を使って再検索します。

この3つすべてに当てはまる落とし穴が1つあります。現在のセッションは、入力したばかりのフレーズに必ず一致します（スキルの引数、コマンド、この推論もすべて現在のセッションの記録に含まれます）。最上位の結果の範囲が数分前から始まっている場合、ほぼ間違いなく現在のセッションです。内部の範囲を確認してから、--exclude-session <id> を指定して再実行すると、実際の結果を確認できます。

セッションファイルの場所

各 Claude の履歴ルートでは、セッションは <history-root>/projects/<encoded-project-path>/<session-id>.jsonl に保存されます。アクティブなルートは自動的に検出されます。永続アーカイブルートは一度 ~/.claude/history-sources.json で設定すると、以降はデフォルトで含まれます。

Claude はチェックポイントのペイロードを <history-root>/file-history/<session-id>/<opaque-backup-name> に保存することもあります。JSONL の file-history-snapshot.snapshot.trackedFileBackups マップは、元の各パスを不透明なバックアップ名とバージョンに対応付けます。この付随ストアは projects/ とは別です。JSONL だけを長期アーカイブにコピーしても、チェックポイントのデータもコピーされたことにはなりません。この形式は、文書化された安定 API ではなく、観察された Claude Code のランタイム詳細です。そのため、同梱の復旧パーサーは選択されたマッピング、バージョンと名前の一致、パスの包含関係、バイト単位の同一性を検証し、これらの事実に食い違いがあれば明示的に失敗します。

ディレクトリ名は、プロジェクトの絶対作業ディレクトリパスに含まれる / をすべて - に置き換えたものです。ベース名だけではありません。 たとえば /Users/<name>/Desktop/my-app は -Users-<name>-Desktop-my-app になります。そのため、my-app だけではディレクトリに直接一致しません。

プロジェクトに履歴がないと結論づける前に、デフォルトのソースセットを使って同梱のコマンドを実行してください。ls の失敗から履歴がないと判断してはいけません。

python3 scripts/analyze_sessions.py list /path/to/project
python3 scripts/analyze_sessions.py search /path/to/project '<keyword>'

何も返さない ls <basename> は、検索に誤った名前を使ったことを意味します。履歴がないという意味ではありません。同梱の analyze_sessions.py は ~ を展開し、絶対パスを解決し、曖昧さのないベース名の逆引きをフォールバックとして行い、設定済みのすべてのソースを検索します。プロジェクトの絶対パス全体を渡すことを推奨しますが、~、相対パス、ベース名も使用できます。

注：Claude Desktop の cowork／組み込み Claude Code モードから実行されたセッションもここに保存されます（Desktop は同梱の CLI を実行します）。Desktop のネイティブチャットだけは別の場所（JSONL ではなく LevelDB ストア）に保存されます。そのため、「Desktop 内で実行した」からといって ~/.claude/projects/ に履歴がないとは限りません。

アクティブなプロファイルと長期アーカイブ — デフォルトでまとめて検索

~/.claude はデフォルトのホームにすぎません。モデルごとのプロファイル（各プロファイルは独自の CLAUDE_CONFIG_DIR を使用）を通じて Claude Code をサードパーティ製モデルで実行するユーザーは、~/.claude には一切保存されない、並行する履歴を蓄積します。

• ~/.claude-profiles/<name>/projects/… — プロファイルごとに 1 つ（例：kimi、deepseek、glm、step の各プロファイル）
• ~/.claude-<name>/projects/… — ときどき存在する兄弟ホーム
• 現在のシェルで CLAUDE_CONFIG_DIR が指す場所

長期アーカイブは、もう 1 つの独立したソース種別です。アクティブなディレクトリに直近のセッションしか残らない一方で、アーカイブにはアクティブなツリーから消えた古い JSONL ファイルが保持されることがあります。そのため、アクティブなホームだけに限定した検索では、メインホームだけを検索した場合と同じ誤検出が起こる可能性があります。

analyze_sessions.py は両方の種別に対応します。list と search は、すべてのアクティブなホームを自動検出してアーカイブレジストリを読み込み、ID でセッションの重複を排除し、コピー間の内部範囲を統合して、すべてのソースラベルを来歴情報として保持します。 キーワード検索は、同一レコードの重複を排除しながらすべての物理コピーをストリーミングするため、同じセッション ID を持つ新しいアクティブコピーがあっても、アーカイブにしかないレコードが検索から漏れることはありません。意図的な診断を行う場合に限り、対象を絞ってください。

# default: active homes + registered archives
scripts/analyze_sessions.py search /path/to/project keyword

# exact diagnostic scope; not a completeness check
scripts/analyze_sessions.py search /path/to/project keyword --main-only

# exact diagnostic scope (repeatable)
scripts/analyze_sessions.py search /path/to/project keyword --home ~/.claude-profiles/kimi

# test a non-default source registry
scripts/analyze_sessions.py search /path/to/project keyword \
  --history-sources /path/to/history-sources.json

履歴がないことの証明に、その場しのぎの生の grep を使わないでください。 レジストリを独自に解析し、すべてのアクティブルートを対象とし、メッセージ以外のイベントペイロードを検索したうえで、内部レコードのタイムスタンプに日付を適用する必要があります。同梱のスクリプトはすでにこれらを行います。

JSONL の詳細な構造と抽出パターンについては、references/session_file_format.md を参照してください。

基本操作

1. プロジェクトのセッションを一覧表示する

特定のプロジェクトのセッションファイルをすべて検索します。

python3 scripts/analyze_sessions.py list /path/to/project

内部 JSONL タイムスタンプの最大値でセッションを並べ替え、内部の全範囲、サイズ、パス、ソースの由来を表示します。ファイルの mtime は使用しません。

オプション：--limit N を指定すると、表示するセッション数を N 件に制限します（デフォルト：10）。また、--from-date または --to-date を指定すると、指定した期間と内部範囲が重なるセッションに絞り込めます。--all-projects を指定すると、すべてのプロジェクトを一覧表示します（エンコードされたプロジェクト名ごとにグループ化）。--exclude-session <id>（複数回指定可能）を指定すると、該当するセッションを除外します。

2. キーワードでセッションを検索する

特定の内容を含むセッションを検索します。

python3 scripts/analyze_sessions.py search /path/to/project keyword1 keyword2

キーワードの出現頻度で順位付けしたセッションが返されます。内容は次のとおりです。

• メンションの合計数
• キーワードごとの内訳
• セッションおよび一致したレコードの内部時間範囲
• 一致したフィールドの種類、セッションの由来、一致の由来
• 主な一致パスと、その他の一致コピー

検索対象には、メッセージ、思考テキスト（署名を除く）、ツールの入力／結果、キュー操作の内容、添付ファイル、直近のプロンプト、システム／要約の内容、カスタムタイトル、ファイル履歴スナップショット内の元のパスが含まれます。オプション：大文字と小文字を厳密に区別する場合は --case-sensitive を指定します。--from-date と --to-date を指定すると、セッションの mtime ではなく、各レコード固有の内部タイムスタンプで一致するレコードを絞り込めます。--exclude-session <id>（複数回指定可能）を指定すると、セッションを除外します。直前に入力したフレーズを検索する場合は、現在のセッションの ID を必ず渡してください。入力したコマンドによって、このセッション自体が一致するためです。

日付のみの範囲指定では、現地時間のその日全体が対象になります。日時の範囲指定には Z または明示的な UTC オフセットが必要です。日付フィルターが有効な場合、内部タイムスタンプが有効でないレコードは、明示的な注記とともに除外されます。移行後やコピー後にファイルの mtime で代用することはありません。

2a. プロジェクトが不明な場合の検索 — --all-projects

必須のプロジェクト引数は推定値をエンコードします。推定が間違っている場合、プロジェクトを指定した検索では「見つからない」という誤った結果が返されます。位置引数を省略して、すべてのプロジェクトを検索してください（list でも同じフラグを使用できます）。

python3 scripts/analyze_sessions.py search --all-projects 'some phrase'

--all-projects を指定すると、すべての位置引数がキーワードとして扱われるため、複数キーワードでの検索が可能です。例：search --all-projects keyword1 keyword2。このフラグを指定しない場合、最初の位置引数はプロジェクトのパス、残りの項目はキーワードになります。

想定される出力：すべてのソースにわたる全プロジェクトのセッションを一度に検索し、一致するたびにエンコードされたプロジェクトディレクトリを示す Project: 行が表示されます。履歴全体を検索するため、大規模なツリーでは数秒ではなく数分かかることがあります。

2b. Codex の履歴を含める — --codex

履歴を持つツールは Claude Code だけではありません。Codex はロールアウトを <codex-home>/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl と archived_sessions/ に保存します（codex home = --codex-home、$CODEX_HOME、または ~/.codex）。スキーマが Claude のものとは異なるため、デフォルトでは検索対象から完全に除外されます。--codex を指定すると、ロールアウトの検索が追加されます。

python3 scripts/analyze_sessions.py search /path/to/project 'some phrase' --codex

Codex の一致結果は、セッション ID、cwd、内部範囲、メンション数、一致したフィールドとともに、独立したセクション（📦）に表示されます。プロジェクトを位置引数で指定すると、session_meta の cwd と再帰的に一致するロールアウトに絞り込まれます。--all-projects を指定すると、すべてのロールアウトが検索対象になります。event_msg のメッセージミラーは、response_item のメッセージテキストと完全に重複するため、1 回だけカウントされます。ロールアウトのレコード形式については、references/session_file_format.md に記載されています。

--codex が拡張するのは検索のみです。Codex のロールアウトには Claude のファイル履歴マッピングがないため、recover_content.py は空の復元結果を成功として返す代わりに、境界に関する明確なエラーで Codex のロールアウトを拒否します。

2c. Kimi CLI の履歴を含める — --kimi

Kimi CLI（kimi-code）は、セッションを次の場所に保存します。 <kimi-home>/sessions/wd_<workspace>_<hash>/session_<uuid>/agents/<agent>/wire.jsonl セッションごとの state.json には、id/cwd/title と、作成・更新時刻のミリ秒単位の範囲が記録されています（kimi home = --kimi-home、$KIMI_HOME、または ~/.kimi-code）。wire スキーマは Claude と Codex のどちらとも異なるため、 デフォルトの検索では完全にスキップされます。--kimi を指定すると wire の検索処理が追加されます。

python3 scripts/analyze_sessions.py search /path/to/project 'some phrase' --kimi

Kimi のヒットは、セッション ID、タイトル、cwd、 内部範囲、言及数、マッチしたフィールドとともに、独自のセクション（🌙）に表示されます。プロジェクトを位置引数で指定すると、state.json の cwd に基づいてセッションがフィルタリングされます（再帰的に照合）。--all-projects を指定すると、すべてのセッションが検索されます。サブエージェントの wire（agents/agent-N/）は同じ会話の実行であるため、ヒットはセッション単位で集約され、各マッチフィールドにはエージェント名が接頭辞として付きます（例： main:message、agent-0:tool_input）。検索対象となるのは会話そのものです。プロンプト（turn.prompt / turn.steer、origin を問わずインデックス化します。検索では意図的に広く拾います）、追加されたメッセージ、アシスタントのコンテンツパート、ツール呼び出し、ツールの結果が含まれます。固定の定型情報（設定／プロファイルのシステムプロンプト、ツールのスナップショット、使用量／トークンのメトリクス）は意図的にインデックス化されません。共有のシステムプロンプトにしか現れないキーワードではすべてのセッションがヒットしてしまうためです。このツールが会話内容について信頼できる答えを返すのは、「見つかりません」です。

--kimi は --codex とまったく同様に、検索のみ対象を広げます。Kimi の wire ログには Claude のファイル履歴マッピングが含まれないため、ファイルの復元は Claude Code JSONL のみが対象です。recover_content.py に Kimi の wire パスを渡さないでください。--codex と --kimi は組み合わせて使用できます。両方のツールを使って開発したプロジェクトでは、同じコマンドに両方のフラグが必要です。

スクリプトが出力する「一致なし」のヒントには、まだ適用されていない --all-projects / --codex / --kimi / より短い部分文字列のいずれかがすでに提示されています。何も見つからないと結論づける前に、stderr を確認してください。

3. 削除されたコンテンツを復元する

選択したセッションからファイルを復元します。

python3 scripts/recover_content.py <session-path-from-search>

各パスについて、デフォルトモードでは同じセッション ID の既知のコピーをすべて統合し、有効なファイル履歴チェックポイントのうち最新のものを選択して、アクティブまたは登録済みアーカイブの補助ストアから正確なバイト列を復元します。これにより、その後の Edit やシェルによる変更も取得でき、バイナリファイルや Write ツール呼び出しのないファイルも復元できます。後続の backupFileName: null は削除の tombstone です。その場合、最後に利用可能なチェックポイントが復元され、後の削除についてレポートに記載されます。パスに利用可能なスナップショットチェックポイントがない場合、スクリプトは最新の Write 呼び出しを復元し、recovery_report.txt で忠実度が低いものとして表示します。対応する tool_result に is_error: true が明示されている Write はスキップされます。試みられただけの書き込みはチェックポイントではありません。元のディレクトリ構造は ./recovered_content/ 内に保持されます。

キーワードによるフィルタリング：

python3 scripts/recover_content.py <session-path-from-search> \
  -k ModelLoading FRONTEND deleted

パスにいずれかのキーワードが含まれるファイルのみを復元します。

出力ディレクトリのカスタマイズ：

python3 scripts/recover_content.py <session-path-from-search> -o ./my_recovery/

登録済みのアーカイブルートと同じ ID の JSONL コピーは自動的に含まれます。 未登録の補助チェックポイントストアが別の場所にある場合は、<session-id>/ ディレクトリを直接含むルートを追加してください。

python3 scripts/recover_content.py <session-path-from-search> \
  --file-history-root /path/to/file-history \
  -o ./my_recovery/

参照先のバックアップがないスナップショットメタデータは、忠実度エラーです。古い Write の内容を黙って代用するのではなく、選択したファイルを書き込む前に復元を中止します。後続の Edit やシェルによる変更が含まれない可能性をユーザーが明示的に了承している場合に限り、--write-only を使用してください。

4. セッション統計を分析する

詳細なセッションメトリクスを取得します。

python3 scripts/analyze_sessions.py stats /path/to/session.jsonl

レポートの内容：

• メッセージ数（user/assistant）
• ツール使用状況の内訳
• ファイル操作数（Write/Edit/Read）

オプション：すべてのファイル操作を一覧表示するには --show-files を指定します。

5. ユーザーメッセージをそのまま抽出する

ユーザーが実際に入力した内容の閲覧ページを生成します — すべてのホームとアーカイブにまたがるすべてのユーザーメッセージを含み、ハーネスのノイズは付録に振り分けられます:

python3 scripts/extract_user_messages.py --days 7

デフォルトで ~/.claude-flow-viewer/user-words.html(プライマリ)と .md を書き出します — 永続的なパスです; /tmp は避けてください(OS が消去します)。別の場所に書き出すには OUT_BASE 位置引数を渡します。便利なフラグ: --group-by project|day(デフォルトは project)、--min-dup N(定型文の頻度しきい値)、--home <path>(正確なスコープ、繰り返し指定可能)。

このタスクの難しい部分はパースではなく、作者の特定です: user レコードは必ずしもユーザーが書いたものとは限りません。抽出器は references/session_file_format.md にある 5 つの混入クラス — コマンドエンベロープ、フック/ループによって注入された定型文(頻度検出、単独形と末尾追記形の両方)、[Image #N] プレースホルダー、ドキュメント全体の貼り付け、エージェントの声による再注入(以前のアシスタントのテキストと内容照合)— を実装し、attachment.queued_command レコードから作業途中の入力を復元し、後から配信されたユーザーレコードとの重複を排除します。フィルターを変更する前に、このリファレンスのセクションを読んでください。

6. セッションの終了をトリアージする(クラッシュ復旧 / バックログ監査)

時間枠またはプロジェクト内でセッションがどのように終了したかを分類し、各セッションの最後のアシスタントメッセージ全体を出力します — 「どのセッションが再起動/クラッシュによって途切れたか」または「どの古いセッションがまだ返信を待っていて、実際には完了していないか」を調べるためのツールです:

python3 scripts/analyze_sessions.py triage --all-projects \
  --from-date 2026-08-05T12:30:00+00:00 --to-date 2026-08-05T13:05:00+00:00

対象範囲内の各セッションのセッション ID(常に完全な形で、決して切り詰められません — 後続のレポートにそのままコピーしてください)、cwd、および 5 つの構造的な kind のいずれかを報告します: interrupted_explicit(そのセッションの最後の関連レコードが明示的な中断マーカー)、net_error(最後のアシスタントのターンが API/トランスポートエラーで失敗)、done(最後のアシスタントのターンが実際のテキストを生成し、それが API エラーで始まっていない)、empty(アシスタントのターンがまったくない)、または stuck_no_result — その他すべての形を受け止める包括的な区分です。トリアージの目的ではそれらはすべて同じことを意味するからです: 最後のターンがテキストによる返信を生成しなかったため、ファイルが止まった時点でモデルはまだ作業中だった。 これには、結果をまだ待っているツール呼び出し、結果はすでに到着したもののその後にアシスタントのターンが続かなかったツール呼び出し(ハーネスが結果の到着とモデルの次のターンのキャプチャの間で停止した可能性が高い)、および思考のみまたはその他の理由で空である最後のターンが含まれます。

done は構造的なラベルであり、何も未解決でないという主張ではありません。 セッションがきれいな text ブロックで終了するのは、まさにアシスタントが発見、決定、または質問を提示して返信を得られなかったからである場合があります — 「完全に完了した」ものと「あなたの返信を待っている」ものを区別するには、出力される last_assistant_text を読む必要があります。だからこそこのコマンドは、切り詰められたタイトルではなく、デフォルトで最大 4000 文字のそれを出力します(上限なしにするには --tail-chars 0)。完全な理由付けについては references/session_file_format.md の「Detect Session Interruption」を参照してください。これが kind フィールドとは本質的に異なる軸である理由も含まれます。

便利なフラグ: --kind KIND(繰り返し指定可能、特定の種類に限定 — 例えば「クラッシュで説明できそうなものだけ」を対象にするには --kind stuck_no_result --kind interrupted_explicit); --exclude-title-prefix TEXT(繰り返し指定可能 — 冒頭のプロンプトが TEXT で始まるセッションを除外します。これは、常に同じ固定プロンプトで始まるコードレビューフックのような、プロジェクト自身の自動化規約に対応するためのものです; そうしたセッションは、中断ではなく定型的な構造化ツール呼び出しで終わるため、そうでなければトリアージの処理を圧倒してしまいます); --tail-chars N(出力される最後のアシスタントのテキストを上限設定; デフォルトは 4000、0 = 無制限)。list と共通の --from-date/--to-date/--home/--main-only/--history-sources、および list と search の両方と共通の --all-projects/プロジェクトパス/--exclude-session を備えています。

ワークフローの例

ファイルの復元、ファイルの変遷の追跡、一括操作など、詳細なワークフローの例については、references/workflow_examples.md を参照してください。

復元のベストプラクティス

重複排除

recover_content.py は同じ ID のセッションコピーを統合し、元のパスごとに最も新しいファイル履歴バージョンを保持します。同じ場合はチェックポイントのタイムスタンプを使用します。後の削除トゥームストーンは、以前の復元可能なバックアップを消去せず、報告される状態を変更します。使用可能なチェックポイントがないパスについては、内部タイムスタンプが最も新しい Write 呼び出しを保持します。コピー間の物理的な JSONL 行順は、十分な時間的証拠とは見なされません。また、明示的に失敗した Write ツールの結果は、その Write の試行を復元対象から除外します。

キーワードの選択

次の場所に含まれる、特徴的なキーワードを選んでください。

• ファイル名またはパス
• 関数名／クラス名
• コード内の固有の文字列
• エラーメッセージまたはコメント

出力の整理

内容がわかる出力ディレクトリを作成してください。

# Bad
python3 scripts/recover_content.py session.jsonl -o ./output/

# Good
python3 scripts/recover_content.py session.jsonl -o ./recovered_deleted_docs/
python3 scripts/recover_content.py session.jsonl -o ./feature_xy_history/

検証

復元後は、必ず内容を検証してください。

# Check directory structure (files preserved in subdirectories)
find ./recovered_content/ -type f

# Read recovery report (shows full output paths)
cat ./recovered_content/recovery_report.txt

# Spot-check content and compare the report's SHA-256 with the source backup
head -20 ./recovered_content/src/components/ImportantFile.jsx

Source: file-history とその SHA-256 は、正確に取得されたチェックポイントの証拠として扱ってください。Source: Write は復元可能なチェックポイントとして扱い、ファイルの最終状態を示す証拠とは見なさないでください。

制限事項

復元できるもの

✅ 利用可能なファイル履歴スナップショットが参照する正確なバイト列 ✅ 付随するファイル履歴ストアに存在するバイナリファイル ✅ 後続のチェックポイントで取得された、Edit またはシェルコマンドによって変更されたファイル ✅ スナップショットのメタデータがない場合に Write を使用して書き込まれたファイル（精度は低くなります） ✅ メッセージまたはツールの結果に明示的に含まれるテキスト（手動での抽出）

復元できないもの

❌ ディスクに書き込まれていないファイル（話題にしただけのもの） ❌ セッション開始前に削除されたファイル ❌ 削除されたスナップショットのペイロード、またはアーカイブ済みの JSONL と一緒にコピーされなかったペイロード ❌ セッション内に記録されていない外部ツールの出力

Edit／Read の記録からパスや Edit 差分を特定できる場合がありますが、それ自体はファイル全体の復元元ではありません。

ファイルのバージョン

• ファイル履歴のバックアップは正確に取得されたチェックポイントであり、その後にチェックポイントに記録されていないファイルシステムの変更がなかったことを保証するものではありません。
• ファイル履歴のエントリーがない場合、Write による復元では後続の Edit やシェルの変更を再構築できません。Edit の記録に含まれるのは差分であり、変更後のファイル全体ではありません。
• ファイル履歴の JSONL／ストアの仕様は、実行時に観測されたもので、今後変更される可能性があります。不正な形式または矛盾するメタデータがある場合は、推測せず、明確にエラーとして扱う必要があります。

トラブルシューティング

セッションが見つからない

# Re-run with the full absolute project path and the default source set.
python3 scripts/analyze_sessions.py list /absolute/path/to/project

# Inspect a custom registry only when diagnosing its configuration.
python3 scripts/analyze_sessions.py list /absolute/path/to/project \
  --history-sources /path/to/history-sources.json

「見つかりません」は、プロジェクト ID の誤りや、ソースの不足が原因であることがよくあります。 出力に Searched N source(s) が表示され、想定される active:<label> と archive:<label> の両方のエントリーが含まれていることを確認してください。--main-only または --home を使用した場合は、これらを指定せずに再実行してください。必須のアーカイブが見つからない場合は修復するか、レジストリのエントリーを意図的に変更する必要があります。エラーを黙って無視して、セッションが存在しないと判断しないでください。ソース一式が揃っていると確認できた場合は、「完全性の不変条件」セクションにある検索範囲を広げる手順に従ってください。--all-projects → --codex → --kimi → より短い部分文字列の順に試し、現在のセッションを --exclude-session で除外してください。

復元結果が空

考えられる原因：

• キーワードがセッション内のファイルパスと一致しない
• セッションがファイル作成より前のものである
• そのパスがファイル履歴にも Write にも記録されていない

解決策：

• Edit 操作を確認するため、--show-edits フラグを試してください
• キーワード検索の範囲を広げてください
• 前後のセッションを検索してください
• 正確なバックアップに関するエラーで付随するストアの欠落が示された場合は、そのストアを見つけて --file-history-root を渡してください。古い Write チェックポイントが最終状態だと判断しないでください

大きなセッションファイル

100MBを超えるセッションの場合：

• セッション全体を読み込まず、JSONLを1行ずつ検索します。
• 復元時はバックアップのバイト列をチャンク単位でそのままコピーし、軽量な編集サマリーを5件だけ保持します。編集前後のペイロード全体は保持しません。
• 復元時も、有効なWriteペイロードとコピーの和集合に必要なレコードのフィンガープリントは保持するため、メモリ使用量は一定ではありません。復元範囲を制限するには -k を使用してください。また、実行時間は検出されたすべての物理コピーに応じて増加します。

セキュリティとプライバシー

復元した内容を共有する前に

セッションファイルには、次の情報が含まれている場合があります：

• ユーザー名を含む絶対パス
• APIキーや認証情報
• 企業固有の情報

共有する前に必ずサニタイズしてください：

# Read-only audit; review every hit before creating a separate redacted copy.
rg -n --hidden -S \
  '(api[_-]?key|password|token|secret|/Users/[^/]+/|/home/[^/]+/)' \
  recovered_content/

recovery_report.txt も機密情報です。このファイルには、要求されたセッションのコピー、元の絶対パス、チェックポイントの場所、出力先のパスが記録されています。復元したファイルとともにレポートも確認して編集し、デフォルトでは共有しないでください。

安全な保管

復元した内容は、元のセッションの機密性を引き継ぎます。安全に保管し、セッションデータの取り扱いに関する組織のポリシーに従ってください。

次のステップ：中断した作業を再開する

関連するセッション履歴を見つけた後は、作業の続行を提案してください：

Found [N] relevant sessions with recoverable context.

Options:
A) Resume work — run /daymade-claude-code:continue-claude-work to pick up where you left off (Recommended)
B) Just show me the content — I'll decide what to do with it

メンテナーによる検証

ソースリポジトリでは、daymade-claude-code/_conversation_core/ が、このスキル、local-conversation-history、continue-claude-work、continue-codex-work で共有されているコードのSSOTです。sync_core.py はこのパッケージを各スキルの scripts/_core/ にバンドルします。バンドルされたコピーを直接編集しないでください。

共有コードを変更した後は、4つすべてのバンドルを同期して検証し、続けてファインダーの分離フィクスチャを実行してください：

uv run python ../sync_core.py sync
uv run python ../sync_core.py check
python -m unittest discover -s tests -p "test_*.py"