> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Kodus Trace

> コーディングエージェントが行った変更の背後にある判断を記録し、パスを指定して読み出します。

差分が示すのは、何が変わったかです。Kodus Trace は、その理由を残します。リポジトリ内のコーディングエージェントのセッションを取得し、プッシュするブランチを判断（アーキテクチャ上の選択、規約、トレードオフ）に変換して、あなたやエージェントが、パスを変更する前にそのパスについて記録された判断を読み出せるようにします。

ローカルでの記録と参照は CLI から利用できます。機密情報を伏せた Trace の判断記録を同じリポジトリの PR レビューで使えるのは、Kodus Cloud の **プライベートアルファ版**です。

## 有効にする

```bash theme={null}
kodus trace enable
```

リポジトリ内で実行します。次のものがインストールされます。

* 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 設定**。

> [!WARNING]
>
> `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` で取得できます。プッシュのたびに、そのブランチの記録は置き換えられます。

## 判断を読み出す

変更しようとしているパスを渡します。サブコマンドは不要です。

```bash theme={null}
kodus trace src/billing/invoice.ts
kodus trace src/billing src/payments --limit 10
kodus trace src/billing --format json
```

ディレクトリを指定すると、その配下に記録されたすべてが返されます。ファイルを指定すると、そのスコープに該当するすべてが返され、そのディレクトリに記録された判断も含まれます。読み出しはお使いのマシンにすでにあるデータを使用し、ネットワーク呼び出しは行いません。`--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`。

## 記録を修正する

```bash theme={null}
kodus trace forget <id>      # The decision is wrong: stop returning it
kodus trace pin <id>         # Always keep this decision
kodus trace pin <id> --remove
```

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

## セッションを閲覧する

```bash theme={null}
kodus trace ui               # http://127.0.0.1:4711 by default
kodus trace ui --port 5000 --no-open
```

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

## 環境変数

| 変数 | 説明 |
| - | - |
| `KODUS_TRACE_HOME` | `~/.kodus` の代わりに、セッションを保存するフォルダ |
| `KODUS_TRACE_AGENT_CMD` | 最初に見つかった CLI の代わりに、判断を書き込むコマンド（例: `claude -p`） |
| `KODUS_TRACE_SKIP` | 任意の値を設定すると、セッションフックと pre-push フックが何も行わなくなります |

## 関連ページ

> [card] [AI エージェント](https://docs.kodus.io/ja/how_to_use/cli/ai_agents.md)
>
> コーディングエージェント向けのスキルとループ。

> [card] [コマンドリファレンス](https://docs.kodus.io/ja/how_to_use/cli/commands.md#kodus-trace)
>
> すべての `kodus trace` コマンド。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.