メインコンテンツへスキップ
差分が示すのは、何が変わったかです。Kodus Trace は、その理由を残します。リポジトリ内のコーディングエージェントのセッションを取得し、プッシュするブランチを判断(アーキテクチャ上の選択、規約、トレードオフ)に変換して、あなたやエージェントが、パスを変更する前にそのパスについて記録された判断を読み出せるようにします。 ローカルでの記録と参照は CLI から利用できます。機密情報を伏せた Trace の判断記録を同じリポジトリの PR レビューで使えるのは、Kodus Cloud の プライベートアルファ版です。

有効にする

リポジトリ内で実行します。次のものがインストールされます。
  • Claude Code(リポジトリの .claude/settings.json)、Cursor(リポジトリの .cursor/hooks.json)、Codex(ホームフォルダの ~/.codex/config.toml)用のセッションフック。--agents claude,cursor で対象を限定でき、--codex-config <path> で別の Codex 設定を指定できます。
  • 2つの git フック。prepare-commit-msg は各コミットメッセージに Kodus-Trace: トレーラーを追加し、コミットをそのセッションに紐付けます。pre-push はバックグラウンドで判断の抽出(distillation)を開始します。
  • 通常の git fetch で共有された判断も取得できるようにする fetch 設定。
pre-push フックは、kodus hook install のレビューフックとファイルを共有します。両方をインストールしていると、プッシュしても判断の抽出が開始されないため、新しい判断は書き込まれません。kodus hook uninstall が削除するのはレビューフックのみで、Trace のフックはそのまま残ります。
実行結果は kodus trace status で確認できます。取得したセッションとターンの数、判断(ローカルと共有)、インストールされたフック、発生した問題が表示されます。フックの削除は kodus trace disable で行います(--dry-run を付けるとプレビューできます)。無効化で削除されるのはフックのみです。取得済みのセッションはお使いのマシンに残り、すでに Kodus に送信されたイベントもそのまま残ります。

取得される内容

エージェントセッションの各ターンについて、プロンプトとレスポンス、エージェントが使用した各ツールの1行サマリー、読み取ったファイルと変更したファイル、実行したコマンド、トークン使用量が取得されます。記録はリポジトリの外の ~/.kodus/sessions に保存され、90日後に削除されます。 CLI はイベントを保存または送信する前に、認識できるシークレットのパターンをマスクします。記録内容に機密データが残ることがあります。記録するセッションに認証情報を含めないでください。新しいセッションの記録を停止するには、kodus trace disable を実行してください。 取得はアカウントがなくても動作します。 ログインまたはチームキーでサインインしている場合、CLI は各セッションの認識したシークレットをマスクしたイベントも Kodus に送信します。プロンプトとレスポンス、エージェントが呼び出したツールとその入出力、読み取ったファイルと変更したファイル、コマンド、トークン使用量、ブランチ、git リモートの URL、コミット ID が対象です。Kodus はそれらを組織向けに保存します。セッションが終了すると、モデルがそれらを読み取って判断を抽出します。組織に BYOK モデルがある場合はそのモデルで、ない場合は Kodus が管理するモデルで実行されます。これらのイベントは、チームの1時間あたり1,000リクエストにカウントされます。

判断の作られ方

git push 時に、バックグラウンドのジョブが、デフォルトブランチにないブランチ上の各コミットを要約します。次に、お使いのマシン上のコーディングエージェント CLI に、それらの要約とブランチで取得されたセッションを判断に変換するよう依頼します。使用されるのは、claude、codex、gemini、cursor-agent のうち最初に見つかったものです。そのツールには、コミットメッセージ、ファイル名、セッションのマスク済みのプロンプトとレスポンスが渡されるため、他の用途と同様にそれらはそのプロバイダーに送られます。いずれもインストールされていない場合、取得は動作しますが、判断は書き込まれません。 このジョブがプッシュを遅らせたり失敗させたりすることはありません。判断は kodus/trace/v1 というブランチに書き込まれ、同じリモートにそのブランチがプッシュされるため、チームメイトのクローンでは git fetch で取得できます。プッシュのたびに、そのブランチの記録は置き換えられます。

判断を読み出す

変更しようとしているパスを渡します。サブコマンドは不要です。
ディレクトリを指定すると、その配下に記録されたすべてが返されます。ファイルを指定すると、そのスコープに該当するすべてが返され、そのディレクトリに記録された判断も含まれます。読み出しはお使いのマシンにすでにあるデータを使用し、ネットワーク呼び出しは行いません。--remote <name> で、判断ブランチを読み出すリモートを選択できます。 各判断には次の情報が表示されます。
  • Type: architectural_decision、convention、tradeoff、implementation_detail、tooling、other のいずれか。
  • Origin: あなたが依頼した場合は human、エージェントが指示なしに選択した場合は agent、一緒に決めた場合は collaborative。
  • Confidence: 判断が書かれた時点で評価された、0 から 1 までの値。
  • Scope(適用されるパス)と source: local(ここで記録された)または branch(他の人が共有した)。
  • id: forget と pin で使用するハンドル。
結果が空であることは正常な応答で、終了コードは 0 です。そのパスについてまだ何も記録されていないか、取得がオフであることを意味します。 パスがサブコマンドと同じ名前(status など)の場合は、-- で区切ります: kodus trace -- status。

記録を修正する

どちらもローカルに保存されます。判断が共有ブランチ上にある場合は、そのブランチにも公開されるため、チームに修正が伝わります。

セッションを閲覧する

ローカルのセッションをブラウザで表示します。読み取るのはローカルのストアのみです。

環境変数

関連ページ

AI エージェント

コーディングエージェント向けのスキルとループ。

コマンドリファレンス

すべての kodus trace コマンド。