keep-codex-fast

Codex を軽快に保つ

このスキルを使って、ローカルの Codex の状態を調査し、安全に保守します。目的は、ユーザーを驚かせたり、継続性を損なったりせずに、ローカルでの負荷を軽減することです。

基本原則：変更を適用する前に、継続性を確保してください。ユーザーが今後も続ける可能性のあるアクティブなリポジトリのチャットについては、アーカイブする前に、包括的な引き継ぎドキュメントと再開プロンプトを作成するよう勧めてください。

安全ルール

• 変更を加える前に調査してください。
• 初回実行は必ずレポートのみとしてください。レポートモードでは、ファイルへの書き込み、バックアップの作成、フォルダーの移動、ローカルの Codex の状態変更を行ってはいけません。
• 変更を適用する前にバックアップしてください。ユーザーがローカルの状態を移動または変更せずにバックアップだけを作成したい場合は、--backup-only を使ってください。
• ファイルは削除せず、アーカイブまたは移動してください。ユーザーのチャット、ログ、ワークツリー、メモリ、スキル、プラグイン、自動化を完全に削除してはいけません。
• セッションやワークツリーを移動する場合は、マニフェストと復元スクリプトを作成してください。
• Codex が実行中の場合は、デフォルトでレポートのみを行ってください。変更を適用するのは、Codex を終了した後、または Codex の終了を待つことをユーザーが明示的に了承した場合に限ります。
• ユーザーから明示的に依頼されない限り、認証情報ファイルを変更またはコピーしてはいけません。ローカルの状態に触れる前に、メモリ／スキル／プラグイン／自動化のファイルをバックアップしてください。
• バックアップフォルダーには Codex のメタデータが含まれる可能性があるため、非公開のローカル成果物として扱ってください。ユーザーが内容を確認する前に、バックアップの公開や共有を求めてはいけません。
• ユーザーから詳細を求められた場合、または --details を実行した場合を除き、スレッド ID、生のチャットタイトル、ローカルパス、プロセスパスを出力してはいけません。
• 変更を適用する前に、今後も続ける可能性のあるアクティブなリポジトリのチャットについて、引き継ぎドキュメントを作成するようユーザーに伝えてください。
• ユーザーが今後も続ける可能性のあるアクティブなリポジトリのチャットをアーカイブする前に、包括的な引き継ぎドキュメントと再開プロンプトの作成を勧めてください。
• 古くても重要なアクティブなリポジトリのチャットは、ユーザーが引き継ぎの存在を確認するか、引き継ぎは不要だと確認するまでアーカイブしてはいけません。

メンタルモデル

モードは3つあります。

• 調査：レポートのみで、書き込みは行いません。
• 保守：通常の --apply では、バックアップを作成し、古いセッションをアーカイブし、古いワークツリーを移動し、ログをローテーションし、不要な設定を整理して、パスを正規化します。スレッドのタイトル／プレビューのメタデータは短縮しません。
• オプションの修復：--apply --repair-thread-metadata-bloat では、バックアップの後、SQLite の表示用タイトル／プレビューの肥大化したメタデータを短縮します。ロールアウトのトランスクリプトはそのまま維持されます。

デフォルトのワークフロー

1. ユーザーに安心してもらえるよう説明します。初回実行は読み取り専用でプライバシーに配慮しており、後で変更を適用する際も、削除ではなくアーカイブします。
2. 同梱スクリプトをレポートモードで実行します。

python scripts/keep_codex_fast.py

3. 次の項目を要約します。
   • アクティブなセッションのサイズ
   • アーカイブ済みセッションのサイズ
   • アクティブなセッションのうち、サイズが大きいもの
   • スレッドメタデータの肥大化：アクティブなタイトル／プレビューの文字数合計、タイトル／プレビューの最大文字数、上限超過件数
   • 古くなった可能性のあるワークツリー
   • ログのサイズ
   • 不正な Windows \\?\ パスの件数
   • config のプロジェクト削除候補
   • Node／開発用プロセスの上位項目
4. 変更を適用する前に、今後も続ける可能性があるアクティブなリポジトリのチャットすべてについて、ユーザーにハンドオフを作成するよう勧めます。ハンドオフを作成すれば、負荷の大きいチャットをアーカイブし、新しいスレッドでドキュメントを参照して再開できることを説明します。
5. 重要な可能性がある、サイズの大きい、または古いアクティブなリポジトリのチャットを特定します。ユーザーが続行したい各チャットについて、次のものを作成または更新します。
   • リポジトリ内のハンドオフドキュメント
   • スレッドの文脈を失わずに新しいチャットを開始できる再開用プロンプト
6. ユーザーが推奨されるメンテナンスの適用を希望する場合は、Codex を終了するか、--wait-for-codex-exit を使用するよう依頼してから、次を実行します。

python scripts/keep_codex_fast.py --apply --archive-older-than-days 10 --worktree-older-than-days 7

7. 適用後に確認します。

python scripts/keep_codex_fast.py

8. 定期的なレポートのみのリマインダーを希望するか、ユーザーに確認します。
   • 複数のリポジトリ／ターミナルで Codex を頻繁に使う場合は毎週
   • 使用頻度が低い場合は隔週
   • 手動でのメンテナンスを希望する場合はリマインダーなし

ユーザーが自動化を希望し、Codex アプリの自動化ツールが利用できる場合は、定期的なレポート／リマインダーの自動化のみを作成します。ユーザーがハンドオフを作成したかどうか自動化では確認できないため、変更を伴うメンテナンスを定期実行することは推奨しないでください。プロンプトには、--apply を渡さないこと、ローカル状態をアーカイブ／移動／削除候補の整理／ローテーション／正規化／削除／変更しないこと、手動での適用はハンドオフを確認して Codex を終了した後にのみ行うようユーザーに注意を促すことを明記します。

Apply の動作

• 重要なメタデータを ~/Documents/Codex/codex-backups/keep-codex-fast-* にバックアップします。
• ピン留めされていない古いセッションを ~/.codex/archived_sessions/ にアーカイブします。
• ローカル SQLite テキストフィールド内の \\?\C:\... のような Windows 拡張パスを正規化します。
• config.toml から存在しない／一時的なプロジェクトブロックを削除候補として整理し、BOM なしの UTF-8 で書き込みます。
• 古くなったワークツリーを ~/.codex/archived_worktrees/ に移動します。
• しきい値を超えた場合に限り、logs_2.sqlite* を ~/.codex/archived_logs/ にローテーションします。
• 負荷の大きい Node プロセスを報告しますが、終了はしません。
• 病的に長いアクティブなスレッドのタイトルと first_user_message のプレビューを報告します。ユーザーが --repair-thread-metadata-bloat で明示的に許可した場合に限り、修復します。

レポートモードでは、これらの変更は一切行いません。件数と仮名化された候補を出力するだけです。診断に生の ID、タイトル、またはパスが必要な場合は、--details を使用します。

推奨ポリシー

• ピン留めされていないチャットは、直近 7～10 日分だけをアクティブに保ちます。
• 古い重要なスレッドにはハンドオフドキュメントを使用します。
• 巨大なチャットを何度も再開するのではなく、ハンドオフドキュメントから新しいスレッドを開始します。
• 複数のリポジトリ／ターミナルで Codex を毎日使用する場合は、毎週メンテナンスを実行します。
• 最初の適用が正常に完了した後、週次または隔週のレポートのみのリマインダーを提案します。定期メンテナンスをユーザーが希望していると決めつけないでください。
• 判断に迷う場合は、チャットをアクティブなままにするか、ユーザーに確認します。ピン留めされているチャット、現在のチャット、または引き続き必要だと明示されているチャットは、ハンドオフなしでアーカイブしてはいけません。
• タイトル／プレビューの修復は、メタデータの修復としてのみ扱います。完全な展開時のトランスクリプトはセッション JSONL に保持されます。SQLite の長さ制限付きフィールドは一覧表示／ナビゲーション用です。

スレッドメタデータの肥大化

threads.title または threads.first_user_message に、表示用のタイトルやプレビューではなく、プロンプトや履歴全体に相当する値が保存されると、Codex Desktop の動作が遅くなることがあります。これは、UI が何かを描画する前のスレッド一覧／ナビゲーション処理に影響します。

このスクリプトは、アクティブなスレッド数、タイトル／プレビューの文字数合計、タイトル／プレビューの最大文字数、設定されたタイトル上限を超えるアクティブなタイトル、設定されたプレビュー上限と 10k 文字の両方を超えるアクティブなプレビューを報告します。

通常の適用モードでは、メタデータ肥大化の候補を報告しますが、修復は行いません。ユーザーが明示的に許可した場合は、バックアップ後、Codex が起動していないときに、次を実行します。

python scripts/keep_codex_fast.py --apply --repair-thread-metadata-bloat

これにより、アクティブな threads.title と threads.first_user_message の値に上限が設定されます。タイトルのデフォルトは 120 文字、プレビューのデフォルトは 240 文字です。また、修復したタイトルを session_index.jsonl に追記します。これは現在の upstream における名前更新の保存方法と一致しており、調整や名前検索で古い全メッセージのフォールバックがすぐに優先されるのを防ぎます。

対象を絞った修復マニフェストには、元の完全なタイトル／プレビューの値が保存されるため、変更を元に戻せます。thread-metadata-repairs.jsonl、restore-thread-metadata.py、バックアップフォルダー全体は、ローカルの非公開アーティファクトとして扱ってください。

これはメタデータ肥大化に対するローカルのメンテナンス用回避策です。非常に大きなロールアウト履歴をアプリのレンダラーがハイドレーションする問題は解決しません。その解決には、upstream でのスレッド読み込みの段階化／ページングが必要です。

引き継ぎドキュメントと再開プロンプト

重要なアクティブなリポジトリのチャットは、アーカイブする前に引き継ぎドキュメントを作成してください。docs/codex-handoffs/YYYY-MM-DD-topic.md のようなリポジトリ内のパス、またはユーザーが承認したドキュメントの保存場所を優先してください。

ユーザーが具体的なテンプレートを希望する場合は、references/handoff-template.md を使用してください。

引き継ぎドキュメントは、古いチャットの内容を永続的なプロジェクトメモリに変換します。新しい Codex スレッドがリポジトリと引き継ぎドキュメントを読めば、元のチャット履歴がなくても作業を続けられるようにします。

続けたいと思われる各アクティブなリポジトリのチャットについて、次のプロンプトを提案してください。

Create a comprehensive handoff document for this repo/session before I archive Codex history.

Include:
- repo/path and branch
- current goal
- what we already completed
- files touched or investigated
- commands/tests already run
- known errors, warnings, or failing checks
- open decisions
- constraints, user preferences, and do-not-touch areas
- the next 3-7 concrete steps

Also include a reactivation prompt I can paste into a fresh Codex chat so it can continue from this handoff without relying on the old chat context.

Save the handoff in a sensible repo-local place like docs/codex-handoffs/YYYY-MM-DD-topic.md unless this repo already has a better handoff location.

引き継ぎドキュメントには、次の内容を記録してください。

• リポジトリ／パスとブランチ
• 現在の目標
• すでに完了した作業
• 変更または調査した主なファイル
• すでに実行したコマンド／テスト
• 既知の失敗や警告
• 未決定事項
• 次に行う具体的な手順（3～7 件）
• 制約、ユーザーの希望、「変更しない」領域

上部または末尾に再開プロンプトを追加してください。

We are continuing from this handoff. Read this document first, inspect the current repo state, verify what still applies, and continue from the next steps without assuming the old chat context is available.

自動化リマインダープロンプト

最初の報告／適用／検証サイクルの後に、次の内容を提案してください。

Use $keep-codex-fast to create a recurring Codex maintenance reminder.

Schedule it weekly if I use Codex heavily, or biweekly if that seems safer.

The reminder should:
- run the keep-codex-fast report first
- never pass --apply or run mutating maintenance automatically
- never archive, move, prune, rotate, normalize, delete, or mutate local Codex state
- remind me to create comprehensive handoff docs and reactivation prompts for active repo chats before any manual apply
- summarize active session size, archived session size, extended path candidates, old session candidates, worktree candidates, log size, and top Node/dev processes
- report heavy Node/dev processes without killing them
- tell me that manual apply should only happen after I confirm handoffs exist or are not needed and Codex is closed

アンチパターン

次のような行動は避けてください。

• セッション、ログ、ワークツリー、メモリ、プラグイン、スキルを恒久的に削除する
• Codex が DB に書き込み中に変更を適用する
• 引き継ぎドキュメントを作成する前に、重要なリポジトリのチャットをアーカイブする
• ユーザーが継続性を必要としているかを確認せず、アクティブな履歴サイズを「悪い」と決めつける
• プレビューメタデータの修復を、実際のロールアウトの文字起こしの削除として扱う
• Node／開発プロセスを自動的に強制終了する
• バックアップと構文解析チェックなしで config.toml を書き換える
• Windows で UTF-8 の TOML ファイルを BOM 付きで書き込む
• 速度向上を普遍的な事実として約束する。ローカル状態のメンテナンスによる結果として説明する
• Codex を頻繁に使ったことをユーザーの落ち度だと感じさせる

ユーザー向けの注意事項

チャット、ワークツリー、ログは完全に削除されるわけではないことをユーザーに伝えてください。これらはアーカイブフォルダーに移動され、復元用ヘルパーが書き込まれます。削除されるのは、存在しなくなったフォルダーを参照するプロジェクトエントリーなど、古くなったメタデータのみです。それも config.toml のバックアップを作成した後に行われます。

また、スレッドのタイトル／プレビューの肥大化を修復する処理は、通常の適用には含まれないことも伝えてください。通常の使用では、タイトル／プレビューの肥大化を報告するだけです。レポートに大きなメタデータペイロードが示されており、SQLite の表示用メタデータは短縮される一方で、実際のトランスクリプトはロールアウト JSONL に残ることをユーザーが理解している場合に限り、任意の追加オプションとして --repair-thread-metadata-bloat を推奨してください。

さらに、バックアップフォルダーには、古いスレッドタイトルや最初のメッセージのプレビューなど、非公開のローカル Codex メタデータが含まれる場合があることも伝えてください。バックアップはローカルに保管し、中身を確認していない限り、公開や共有は避けるようにしてください。