TraceCC - エージェントトレース検索・分析

tracecc CLIを使用してコンパイルされたエージェントセッショントレースを検索、レンダリング、および分析します。

コマンド

Compile (バンドルの再構築)

バンドルが古い場合または存在しない場合のみ再コンパイルします。コンパイルは ~/.TraceCC/config.toml から設定されたすべてのトレースルートを走査し、SQLiteバックアップの単一 .tcc ファイルを生成します。

tracecc compile --bundle traces.tcc --redact default --json

潜在的なシークレットをスクラブするため、常に --redact default を使用してください。default ポリシーはAPIキー、トークン、シークレット、認証情報を削除します。現在のところこれが唯一のポリシーです。

プロジェクトスコープに関わらずすべてをコンパイルするには:

tracecc compile --bundle all.tcc --redact default --all

Search

主要なツール。2つのモード:

BM25 (ランク付き関連度) - 自然言語クエリ(「どんなエラーが発生したか」「スケジューリングの話題」)に推奨。関連度でランク付けされた結果を返します:

tracecc search traces.tcc --query "scheduling API cron" --mode bm25 --limit 10

Regex (完全一致パターン) - 関数名、エラーメッセージ、特定の文字列に使用。ドキュメント順で結果を返します:

tracecc search traces.tcc --query "summarize_diff" --mode regex --limit 10

デフォルトモードはregexです。迷った場合はbm25を使用してください — 曖昧なクエリをより適切に処理します。

フィルタで結果を絞り込みます:

• --roles user,assistant,tool_call,tool_result,tool_error - メッセージロールでフィルタリング 有効なロール: user, assistant, tool_call, tool_result, tool_error, system, thinking, meta
• --since 2026-04-01 / --until 2026-04-11 - 日付範囲 (YYYY-MM-DD)
• --project, --model, --runtime - メタデータでフィルタリング (inspect --sessions で有効な値を確認できます)
• --limit N - 最大結果数 (デフォルト 20)
• --format json または --format ndjson - マシン可読形式での出力

一般的なパターン:

# 最近発生したエラーは?
tracecc search traces.tcc --query "error" --mode bm25 --roles tool_error --since 2026-04-01

# ユーザーがあるトピックについて何を尋ねたか?
tracecc search traces.tcc --query "docker kubernetes" --mode bm25 --roles user --limit 10

# 特定の関数または変数を検索
tracecc search traces.tcc --query "PersistentClaude" --mode regex --roles assistant,tool_call

Render

セッションのコンテンツを異なるビューで表示します。すべてのビューは正規のラインナンバーを共有します。

# 最新セッションの人間が読みやすい概要
tracecc render traces.tcc --view ui --session latest

# 完全な無損失トランスクリプト
tracecc render traces.tcc --view full --session <session-id>

# クエリ駆動プロジェクション (関連ブロックのみを表示)
tracecc render traces.tcc --view adaptive --query "topic" --session <session-id>

--session フラグはセッションID、latest、または all を受け入れます:

• latest (デフォルト): 最新のセッションをレンダリング
• <session-id>: 特定のセッションをレンダリング (IDは inspect --sessions または検索結果から取得できます)
• all: すべてのセッション全体でレンダリング — トピックが複数セッションにまたがる場合は --view adaptive と共に使用します

Inspect

バンドルの内部を検査し、検索結果のポインタを逆参照します。有効なフィルタ値を確認するのにも便利です。

# すべてのセッションをリスト (セッションID、プロジェクト、モデル、ランタイムを表示)
tracecc inspect traces.tcc --sessions

# 特定のノードを確認 (ノードIDは内部IR識別子で、ラインナンバーではありません)
tracecc inspect traces.tcc --node 42

# 検索結果ポインタからラインレンジを逆参照 (例: "session:L120-L160")
tracecc inspect traces.tcc --lines 120:160

検索結果 → inspect ワークフロー: 検索結果には session:L71-L72 のようなポインタが含まれます。ラインナンバーを抽出して --lines に渡すと、その位置の完全なテキストが取得できます。

Export

テキストファイルをダウンストリームツールまたはアーカイブ用に書き込みます。

# 最新セッションをエクスポート
tracecc export traces.tcc --out exports/ --overwrite

# すべてのセッションを別々のファイルとしてエクスポート
tracecc export traces.tcc --split-sessions --out exports/ --overwrite

ワークフロー

「Xについて何と言ったか?」 / 「どのセッションで...」

1. BM25検索で広いクエリから開始、limit 10
2. 結果がノイジーな場合は --roles または --since フィルタを追加
3. 結果のセッションIDを使用して render --view ui でコンテキストを確認
4. ユーザーが正確なテキストが必要な場合は、検索結果のラインレンジで inspect --lines を使用

「どんなエラーが起きているのか?」

1. search --roles tool_error --mode bm25 --query "error" --limit 20
2. 出力をセッションIDでグループ化
3. 興味深いエラーのあるセッションのUIビューをレンダリング

「最近のセッションを表示」

1. inspect --sessions を実行して tail -20 でパイプして最新のものを表示
2. 特定の日付範囲の場合: search --since YYYY-MM-DD --until YYYY-MM-DD --roles user --query "." --mode regex --limit 20

バンドルが存在しないまたは古い場合

動的コンテキストにバンドルがないか、バンドルが古い場合:

1. 再コンパイル: tracecc compile --bundle traces.tcc --redact default --json
2. 出力でセッション/イベント数を確認
3. ユーザーのクエリを続行

出力

検索結果は簡潔に提示してください。各ヒットについて以下を表示します:

• セッションID (最初の8文字に短縮)
• 括弧内のロール
• 日付 (利用可能な場合)
• マッチしたコンテンツ (完全なブロックではなく最初の2-3行)

セッション全体をレンダリングする場合は、UIビューを使用して主要な交換を要約し、トランスクリプト全体をダンプしないでください。

ルール

• コンパイル時は常に --redact default を使用してください
• ユーザーが求めない限り、生のバンドルパスまたは内部IDをユーザー向け出力で公開しないでください
• 検索で何も返されない場合は、「見つかりません」と報告する前に別のクエリフレーズやより広いフィルタを試してください
• バンドルはコンパイル後は読み取り専用です。検索とレンダリングは決して変更しません。
• 再コンパイルはユーザーから要求された場合、またはバンドルが明らかに古い場合のみ実行してください