ctxrs/ctx

ctx エージェント履歴検索

ctxは、過去のコーディングエージェントセッションを参照する必要があるときに使用します。これらのトランスクリプトには、ユーザーの意図、決定事項、過去の作業タイムライン、過去の試行、成功または失敗した内容が含まれています。

このスキルは2つのモードで使用します。

• 作業前の検索（retrieval before work）: 以前のセッションに現在のタスクに影響を与える決定、コマンド、失敗、引用が含まれている場合。
• 履歴調査レポート（history research reports）: ユーザーがエージェントまたは読み取り専用サブエージェントに、ローカルの過去のエージェントセッション全体にわたって歴史的なトピックを調査するよう依頼した場合。

前提条件

• ctx CLIがインストールされ、セットアップされている必要があります。インストールされておらず、タスクに適している場合は、以下でインストールします。

  curl -fsSL https://ctx.rs/install | sh
  

• 初回セットアップは、ctxが過去のセッションをインデックス化するため時間がかかることがあります。必要に応じて、バックグラウンドまたはtmux内で実行し続けるか、完了するまで待機します。

• ctxが利用できない場合は、ローカル履歴検索は利用できないと伝え、結果を捏造しないでください。

ワークフロー

1. コールドコンテキストから開始する場合、ctxの準備ができていることを確認します。

   ctx status
   ctx sources
   

   ctx status --format json または ctx sources --format json は、スクリプトが正確なフィールドを必要とする場合にのみ使用します。

2. まず通常の自然言語で検索します。必要に応じて、用語やフィルターを追加します。

   ctx search "<query>"
   ctx search "<query>" --refresh off
   ctx search "<query>" --provider codex
   ctx search "<query>" --workspace <workspace>
   ctx search "<query>" --file <path>
   ctx search "<query>" --since 30d
   ctx search "<query>" --term "<related term>" --term "<error text>"
   ctx search "<query>" --session <ctx-session-id>
   ctx search "<query>" --verbose
   

   エージェントが読むには、デフォルトのテキスト出力を使用します。検索や表示に --format json を追加しないでください。ただし、jq やスクリプトにパイプする場合、または機械可読な正確なフィールドが必要な場合は除きます。JSON出力ははるかに大きく、コンテキストウィンドウをすぐに消費する可能性があります。

   プロンプトが複数のセッションにわたるトピックの履歴やレポートを要求する場合は、異なる表現やフィルターを使用して複数の ctx search クエリを実行し、有望なセッションを見つけます。セッションが関連性があり、そのセッションからの詳細なイベントレベルの一致が必要な場合は、スコープ指定された ctx search "<query>" --session <ctx-session-id> を使用します。

   デフォルトの検索はプライマリエージェントセッションを返すため、人間の意図と決定が目立つようになります。実装の詳細、コードレビューノート、テスト出力、またはサブエージェントセッションからの失敗トレースが重要と思われる場合は、--include-subagents を使用します。

   完全なctx ID、プロバイダID、引用、およびJSONに切り替えずにコピー可能なフォローアップコマンドが必要な場合は、--verbose を使用します。

   セッショントランスクリプトを一時ファイルに書き込み、ファイルサイズを確認してから、関連部分を読み取ることができます。

   ctx show session <ctx-session-id> --format markdown --out /tmp/ctx-session.md
   wc -c /tmp/ctx-session.md
   

   Codexでは、CODEX_THREAD_ID が利用可能な場合、ctxはデフォルトでアクティブなセッションツリーを除外するため、現在のプロンプトとサブエージェントが履歴検索を支配することはありません。アクティブなセッションツリーをターゲットにする場合にのみ --include-current-session を使用します。

3. 結果に依存する前に、関連する結果を検査します。

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

4. ソースの識別や再開のヒントが重要な場合、元のプロバイダ素材を特定します。provider_session_id はCodexの再開UUIDです。

   ctx locate event <ctx-event-id>
   ctx locate session <ctx-session-id>
   

5. あなた、人間、または別のエージェントがファイルを必要とする場合、関連セッションのトランスクリプトを書き出します。

   ctx show session <ctx-session-id> --format markdown --out <output-path>
   

検索を絞り込む必要がある場合

結論を導き出す前に、クエリを変化させ、検索フィルターを使用します。有用なフォローアップには、詳細なイベント検索、セッションスコープ検索、ソースロケーションチェックが含まれます。

ctx search "<query variant>" --events --refresh off
ctx search "<query>" --session <ctx-session-id> --refresh off
ctx search "<query>" --include-subagents --refresh off
ctx show event <ctx-event-id> --window 5
ctx show session <ctx-session-id>
ctx locate event <ctx-event-id>
ctx locate session <ctx-session-id>

検索結果ウィンドウには制限があります。返されたヒット数から、コーパス全体の正確なカウントや完全な監査を主張しないでください。要求された結論が検索、表示、位置情報の証拠で裏付けられない場合は、その制限を述べ、代わりに最も強力に取得された証拠を報告します。

高度なクエリや完全な決定論的イベント列挙には、ctx list events を使用します。使用前に、完全なフィルター、範囲、カーソル、出力ドキュメントを読んでください。

ctx docs show event-queries

履歴調査レポート

歴史的なトピックの調査を依頼された場合は、ユーザーが編集も要求しない限り、読み取り専用のままにしてください。エージェントがレポートを作成し、ctxはローカルソース素材を取得するだけです。

1. プロンプトがあいまいな場合は、トピック、範囲、および希望する長さを再確認します。デフォルトでは簡潔なレポートを優先します。ユーザーが時系列、代替案、または詳細な証拠を求める場合は、より長いレポートを使用します。

2. いくつかのターゲット検索を実行します。クエリ用語を、ユーザーの表現、ファイル名またはモジュール名、エラーテキスト、コマンド、ブランチ名、決定用語にわたって変化させます。ctx search "<topic>" から始め、--term で広げるか、--workspace、--provider、--file、--since、または --session <ctx-session-id> で絞り込みます。レビュー、実装の試行、テスト出力、または失敗トレースが委任されたセッションに存在する可能性が高い場合は、--include-subagents を使用します。レポートがローカルのctxインデックスを更新してはならない場合は、--refresh off を追加します。

3. 結論を導き出す前に、焦点を絞ったソースを検査します。ヒットとその近くのターンには ctx show event を、セッション全体のアークが重要な場合は ctx show session を優先します。

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

   デフォルト出力が必要な証拠を省略する場合にのみ、フルモードまたはログモードを使用します。

4. セッション間で証拠を比較します。一致、矛盾、古い結果、および検索で証拠が見つからなかったギャップに注意します。

5. 引用付きのエージェント合成としてレポートを作成します。

簡潔なレポートの形式：

• 回答または発見。
• 最も強力な裏付けとなるctx ID。
• 重要な注意点またはギャップ。
• オプションの次の検索または検証ステップ。

詳細なレポートの形式：

• 質問と範囲。
• 検索方法（主要なクエリとフィルターを含む）。
• 発見事項または時系列。
• プロバイダ、ctxセッションID、利用可能なctxイベントID、各ソースが重要な理由を示す証拠表。
• 矛盾、ギャップ、および提案されたフォローアップ。

引用ルール

• ctx素材が回答や実装に影響を与える場合は、引用します。
• プロバイダ、ctxセッションID、利用可能なctxイベントID、利用可能なプロバイダセッションIDを含めます。
• 複数のスニペットを統合する場合は、結論を自身の合成としてラベル付けし、裏付けとなるスニペットを引用します。
• 引用されたイベントまたはセッションが現在のCore生成に存在しない場合は、その旨を述べ、明示的な ctx import が適切かどうかを検討します。

安全ルール

• エージェントが読むにはテキスト出力を優先します。JSONはスクリプト、jq、または正確なフィールド抽出にのみ使用し、JSON出力は小さく保ちます。
• 引用されたテキストがその決定を明示的に述べていない限り、ctxが決定を推論したと言わないでください。
• ctxがモデル分析を書いたと述べないでください。
• 生のトランスクリプト、大きなJSONペイロード、シークレット、トークン、またはプライベートパスをユーザー向けレポートに貼り付けないでください。レビューした証拠を要約し、主張を裏付けるために必要な短い抜粋のみを引用します。
• ユーザーが明示的にレビューした抜粋を共有するよう要求しない限り、~/.ctx、プロバイダのトランスクリプトパス、およびJSON出力はプライベートなローカル履歴として扱います。