> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainloop.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# How to trace AI coding sessions
> Record AI coding sessions with `chainloop trace` — across a repository or around a single agent run.
This is a preview/beta feature. Further changes are expected.
## Overview
`chainloop trace` records AI-assisted coding sessions and pushes them to Chainloop as signed [`CHAINLOOP_AI_CODING_SESSION`](/concepts/material-types) attestations. This guide walks through setting it up end to end. For the underlying model — what a session is, how it's correlated with PRs, and how the dashboard metrics are computed — see the [AI Coding Sessions](/concepts/ai-coding-sessions) concept page.
The command is part of the open-source Chainloop CLI, so recording sessions and storing them as signed evidence works against any Chainloop instance — including the self-hosted [Evidence Store](/guides/deployment/oss). The policy library, the session UI, and pull request correlation come with the Enterprise Edition. See [Open Source vs. Enterprise Edition](#open-source-vs-enterprise-edition) at the end of this guide for the split.
## Two Ways to Record
| | [In your repository](#record-sessions-in-your-repository) | [A single agent run](#record-a-single-agent-run) |
| ------------------------- | --------------------------------------------------------- | ---------------------------------------------------- |
| **What it records** | Every AI session in the repository, pushed on `git push` | One agent execution, attested when the command exits |
| **What it leaves behind** | Committed configuration and installed hooks | Nothing — every hook and artifact is removed on exit |
| **Best for** | Developer machines and shared repositories | CI jobs, containers, and sandboxed agent runs |
Most teams want the first one: set a repository up once and every session in it is recorded from then on. Reach for the second when you want the record of what an agent did without leaving anything in the repository — or when there's no repository at all.
## Prerequisites
* **Latest Chainloop CLI**, authenticated against your Chainloop instance:
```bash theme={"dark"}
curl -sfL https://dl.chainloop.dev/cli/install.sh | bash -s
chainloop auth login
```
`chainloop trace` ships in the open-source CLI, so either edition works — add `-- --oss` or `-- --ee` to the install command to pick one explicitly. See [CLI installation](/command-line-reference/cli-installation) for the full set of options. Both user tokens and service accounts work.
* A [Chainloop project](/concepts/projects-versions) to associate sessions with — `chainloop trace init` offers to create one if you don't have it yet.
* A Git repository with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) configured.
`chainloop trace` supports **Claude Code** and **opencode** sessions with full metrics (token usage, cost, tool counts, and conversation metrics). Cursor support is experimental and incomplete (no usage metrics or cost). Support for additional AI coding agents is planned.
## Record Sessions in Your Repository
Run this once from your repository root:
```bash theme={"dark"}
chainloop trace init
```
It asks which organization and project the sessions belong to, and which AI agents to record — offering whatever `.chainloop.yml` already holds, so pressing Enter in an already-configured repository keeps it. You need to be logged in: the command creates the Chainloop workflow the attestations target before it writes anything to the repository.
When it finishes, the repository has:
* **`.chainloop.yml`** at the root, holding the organization, project, and workflow that every push reads.
* **The hook configuration for each agent you picked** — `.claude/settings.json`, `.cursor/hooks.json`, and/or `.opencode/plugins/chainloop-trace.ts`.
* **Git hooks** that build and push the attestation on `git push`.
Passing a flag skips the matching question; see the [CLI reference](/command-line-reference/cli-reference) for the full list.
If you already have git hooks in place, `chainloop trace` backs them up automatically and chains them — your existing hooks continue to run as before.
**Commit `.chainloop.yml` and the agent configuration files.** Git hooks live in `.git/hooks`, which git doesn't carry between clones, so each teammate still runs `chainloop trace init` once — but with those files committed, the command has nothing left to ask them. They only need the [Chainloop CLI](#prerequisites) installed and authenticated.
### Work as Usual
Once initialized, there's nothing else to do. Write code with your agent, commit, and push.
```bash theme={"dark"}
# Start an agent session and work on your code
# ... make changes, commit ...
git push origin my-branch
# pre-push hook automatically creates the attestation
```
The pre-push hook only creates attestations for commits linked to an AI session. Regular (non-AI-assisted) commits pass through without overhead.
## Record a Single Agent Run
This mode is newer than repository recording and still taking shape — expect its flags and output to change.
`chainloop trace init` sets a repository up once and records every session in it. `chainloop trace run` does the opposite: it wraps a single agent invocation, records that one run, and leaves nothing behind.
```bash theme={"dark"}
chainloop trace run \
--org my-org \
--project my-project \
--workflow ai-coding-session \
-- claude -p "fix the failing tests"
```
The command installs the agent hooks, runs the wrapped command, and attests the session once it exits successfully. On the way out it removes every hook and local artifact and restores any agent settings file it touched, so nothing leaks into the next run. If the wrapped command fails, no attestation is pushed and the command's exit code is propagated — which makes `trace run` safe to drop into a CI step.
It ignores `.chainloop.yml` entirely, so the attestation identity comes from the flags: `--org`, `--project`, and `--workflow` are required on every invocation. Agent selection works the same way as in `trace init`, and `--version` pins the project version.
Two things make this the mode for recording *agents* rather than *repositories*:
* **It doesn't need a git repository.** Run it in a scratch directory or a sandbox and the session is still recorded, without commit attribution.
* **It records the session even when it produced no commits.** A run that only read code, ran tests, or answered a question is attested like any other.
| | `trace init` | `trace run` |
| ------------------ | ---------------------------------------------------- | ------------------------------------------------------------ |
| **Configuration** | Reads and writes `.chainloop.yml` | Ignores `.chainloop.yml`; identity comes from flags |
| **Required flags** | None — it asks | `--org`, `--project`, and `--workflow`, every time |
| **Trigger** | `git push` (pre-push hook) | The wrapped command exiting successfully |
| **Git repository** | Required | Optional — without one, sessions carry no commit attribution |
| **Commits** | Attests commits linked to a session | Attests the session even when it produced no commits |
| **On failure** | Push is warned about, or blocked with `requireTrace` | No attestation; the wrapped command's exit code is returned |
**Everything up to this point works on any Chainloop instance**, including the open-source [Evidence Store](/guides/deployment/oss). The session UI, pull request correlation, and the AI Coding dashboard that follow are Enterprise Edition features — see [Open Source vs. Enterprise Edition](#open-source-vs-enterprise-edition).
## Visualize AI Coding Sessions
Once a session has been pushed, you can inspect it directly in the Chainloop Web UI. Navigate to the workflow run that contains the `CHAINLOOP_AI_CODING_SESSION` material.
### Rendered View
Chainloop renders a structured summary of the session — model usage, token consumption, estimated cost, tool invocations, code changes, and per-line attribution.
The attribution breakdown shows which files were modified by AI vs human, with exact line ranges and aggregate statistics.
### Raw View
Switch to the raw view to see the full JSON evidence as captured by the hooks. This is useful for debugging policies or understanding the exact data available for Rego evaluation.
Inspect any `CHAINLOOP_AI_CODING_SESSION` material the same way you inspect other evidence types — click on the material in the workflow run details to toggle between rendered and raw views.
## Pull Request Correlation
When a pull request or merge request is opened or updated, Chainloop posts a summary comment listing every AI coding session that contributed to it and, when policies fire, a `Chainloop AI Policies` result on the head commit. Both require the repository to be connected to Chainloop.
**GitHub and GitLab are both supported.** The summary comment is posted the same way on a GitHub pull request and a GitLab merge request. The policy result differs by provider: GitHub gets a [check run](#chainloop-ai-policies-check-run) carrying the full rendered summary, while GitLab — which has no check-run equivalent — gets a commit status named `Chainloop AI Policies` with a one-line description and a link to the details in Chainloop.
### Connect Your Repository
Connecting is a one-time, organization-level action: **GitHub** installs the Chainloop GitHub App, **GitLab** registers a connection with an access token. See [Connect GitHub & GitLab](/guides/connect-repository) for both flows. If your repository is already enrolled — for [keyless attestations](/guides/github-keyless), for example — you're done.
On GitHub, the app requests these permissions:
| Scope | Why |
| ------------------------------- | -------------------------------------------------------- |
| **Metadata: Read** | Identify the repository (default GitHub App requirement) |
| **Code: Read & Write** | Read commit metadata to correlate sessions to PR commits |
| **Pull requests: Read & Write** | Post and update the AI session summary comment on PRs |
| **Checks: Read & Write** | Publish the `Chainloop AI Policies` check run |
Subscribed webhook events: **Pull request** — opens, syncs, and reopens trigger correlation. On GitLab, the equivalent merge request events do the same.
Chainloop stores only repository metadata (ID and name), not your repository code.
Once the provider is connected, link the repository from the project that receives the attestations — it's the **Connect a repository** step of the [Create Project wizard](/get-started/projects/create-project), and a project created without one can be linked later.
Attestations from repositories that aren't linked to a project are still accepted, but **correlation won't work** — Chainloop can't tell which project the pull or merge request belongs to, so no summary comment, policy result, or dashboard PR metrics will appear.
### Summary Comment
Two parts:
* **Aggregate table** — one row per contributing session, with the agent and version, model, [AI Session Score](/reference/ai-score), attribution %, files touched, lines added/removed, tokens in/out, estimated cost, and session duration. Attribution % counts both added and removed lines.
* **Per-session file breakdown** (collapsible) — status, attribution label, file path linked to the blob at the PR head, and lines added/removed for each file the session modified. Each session block also includes its [AI Session Score](/reference/ai-score) breakdown — per-criterion scores and the findings reviewers should focus on.
### `Chainloop AI Policies` Check Run
When you've attached policies to `CHAINLOOP_AI_CODING_SESSION` (see [Applying policies](#applying-policies) below), Chainloop publishes a check run on the PR head commit — or, on GitLab, a commit status of the same name:
* `failure` — fails when **either** of the following is true:
* **Policy violations in the aggregated session** — any attestation generated during the same AI session has a policy violation. Sessions are aggregated by their commit-message trailer, so a single failing material in any of the session's attestations fails the check.
* **Missing session attestations** — a session referenced in a commit's trailer can't be found in Chainloop (typically because its attestation push failed for that session).
* `neutral` — policy data couldn't be evaluated. GitLab has no neutral state, so this surfaces as a `skipped` commit status.
* `success` — every referenced session is present and every aggregated session passes its policies.
This makes AI policy compliance a first-class merge gate. On GitHub it requires the `checks:write` permission; on GitLab, a connection token that can write commit statuses.
### When It Runs
* The summary is posted when the PR is opened and re-evaluated every time new commits are pushed.
* Closed or merged PRs are not updated — the last posted summary stays in place.
* No comment is posted when none of the PR's commits match a stored AI coding session.
## Use the AI Coding Dashboard
For an organization-wide view across every recorded session, open **Dashboards → AI Coding** in the sidebar (`/u//dashboards/ai`). The dashboard aggregates every `CHAINLOOP_AI_CODING_SESSION` attestation pushed to the org.
Use the time-range selector in the top right to switch between **24 hours**, **7 days**, **30 days**, and **3 months**. Each card shows the delta vs. the previous period of the same length.
The cards on the dashboard are: **Total Sessions**, **Active Users**, **AI-assisted PRs**, **AI-authored Code**, **Top Users**, and **Model Breakdown**. What each card shows and which backend metric drives it is documented in [AI Coding Sessions → AI Sessions Dashboard Metrics](/concepts/ai-coding-sessions#ai-sessions-dashboard-metrics).
The dashboard only includes sessions that have been pushed as attestations. If a developer hasn't set up recording yet, their work won't appear here.
## Applying Policies
Define `CHAINLOOP_AI_CODING_SESSION` in your contract to attach policies to recorded sessions. Chainloop ships a curated contract of [built-in policies](/concepts/ai-coding-sessions#built-in-policies) you can opt into with the Enterprise Edition; the examples below show three custom Rego policies you can write yourself, which work on any Chainloop instance since the policy engine is open source.
```yaml contract.yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Contract
metadata:
name: ai-session-governance
spec:
materials:
- type: CHAINLOOP_AI_CODING_SESSION
name: ai-coding-session
policies:
materials:
- ref: file://check-approved-models.yaml
```
### Example: Restrict to Approved Models
```yaml check-approved-models.yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Policy
metadata:
name: check-approved-models
description: Ensure AI coding sessions only use approved models
spec:
policies:
- kind: CHAINLOOP_AI_CODING_SESSION
embedded: |
package main
import rego.v1
valid_input if {
input.data.model.models_used
}
approved_models := {"claude-opus-4-6", "claude-sonnet-4-6"}
violations contains msg if {
valid_input
some model in input.data.model.models_used
not model in approved_models
msg := sprintf("Model '%s' is not approved for AI coding sessions.", [model])
}
```
### Example: Enforce a Token Budget
```yaml check-token-budget.yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Policy
metadata:
name: check-token-budget
description: Flag sessions that exceed a token budget
spec:
policies:
- kind: CHAINLOOP_AI_CODING_SESSION
embedded: |
package main
import rego.v1
valid_input if {
input.data.usage.total_tokens
}
max_tokens := 500000
violations contains msg if {
valid_input
input.data.usage.total_tokens > max_tokens
msg := sprintf("Session used %d tokens, exceeding the %d token budget.", [input.data.usage.total_tokens, max_tokens])
}
```
### Example: Limit the AI-Authored Code Ratio
```yaml check-ai-code-ratio.yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Policy
metadata:
name: check-ai-code-ratio
description: Flag sessions where AI-authored code exceeds a threshold
spec:
policies:
- kind: CHAINLOOP_AI_CODING_SESSION
embedded: |
package main
import rego.v1
valid_input if {
input.data.code_changes.lines_added > 0
}
max_ai_ratio := 80
violations contains msg if {
valid_input
total := input.data.code_changes.lines_added
ai := input.data.code_changes.ai_lines_added
ratio := (ai * 100) / total
ratio > max_ai_ratio
msg := sprintf("AI authored %d%% of added lines (%d/%d), exceeding the %d%% threshold.", [ratio, ai, total, max_ai_ratio])
}
```
## Enforcing Chainloop Trace
Recording AI sessions is opt-in by default — if a developer hasn't set it up, or an attestation push fails for any reason, the work simply doesn't appear in Chainloop. When AI traceability is mandatory, you can enforce it at three different points: locally on push, on the attestation itself, and on the pull request.
### Block the push when attestations fail
Set `requireTrace: true` in `.chainloop.yml` (or pass `--require-trace` to `chainloop trace init`) to make the pre-push hook fail the `git push` if a session attestation can't be produced — for example, when the developer isn't authenticated, the network is unreachable, or the Chainloop instance rejects the attestation. Without it, the same conditions only emit a warning and the push proceeds.
```yaml .chainloop.yml theme={"dark"}
projectName: my-project
organization: acme-corp
requireTrace: true
```
Both `.chainloop.yml` and `.chainloop.yaml` are accepted. If both exist, `.chainloop.yml` wins. Commit this file to the repository so your team shares one source of truth.
### Gate the attestation with policies
Attach policies to `CHAINLOOP_AI_CODING_SESSION` and enable [control gates](/concepts/control-gates) at the org level (or per policy). When a gated policy fails, the attestation push returns a non-zero exit code, which propagates to the pre-push hook and **interrupts the `git push`** — the developer can't push code that violates AI policy. With the Enterprise Edition, pair this with the [built-in policies](/concepts/ai-coding-sessions#built-in-policies) for signed commits, agent allowlists, dangerous-command detection, and secret scanning; on an open-source instance, attach your own Rego or WASM policies instead.
### Detect missing sessions on the pull request
This last mechanism needs the Enterprise Edition and a connected repository. `chainloop trace` adds a trailer to every commit produced by an AI session, listing the session IDs that contributed to that commit. When Chainloop correlates a pull or merge request, it compares those trailers against the session attestations it holds, and the [`Chainloop AI Policies` result](#chainloop-ai-policies-check-run) fails when any referenced session is missing — typically because its push failed and was never retried. This catches the case where `requireTrace` is off and a developer's attestation silently dropped.
A developer who deliberately wants to bypass detection on a specific PR can add a `skip-ai-session` label to the pull or merge request; Chainloop will skip the missing-session check for it. Use this sparingly — it's an explicit opt-out that's visible on the PR and reviewable.
## Removing Tracing
To uninstall all hooks and clean up local state:
```bash theme={"dark"}
chainloop trace uninstall
```
This removes the Git hooks, the installed agent hooks (for example the Claude Code hooks in `.claude/settings.json`), and the `.git/chainloop-trace/` directory. If existing hooks were backed up during installation, they're restored. Pass `--yes` to skip the confirmation prompt.
## Troubleshooting
If hooks aren't producing attestations or the dashboard looks empty, work through this list before opening a support ticket:
* **Use the latest Chainloop CLI** and confirm it's authenticated against your Chainloop instance:
```bash theme={"dark"}
curl -sfL https://dl.chainloop.dev/cli/install.sh | bash -s
chainloop auth login
```
Both user tokens and service accounts work.
* **Cursor support is experimental and incomplete** — for example, no usage metrics or cost data are captured. Use Claude Code if you need full coverage.
* **Confirm the git hooks fire on `git push`** — you should see `chainloop trace` log lines in the push output. If you don't, re-run `chainloop trace init` from the repository root.
* **Run from the repository root** — Claude Code hooks don't trigger when you launch the agent from a sub-folder of the repository.
* **Check the hook log** at `.git/chainloop-trace/log.txt` — it records every hook invocation with full detail and is the first place to look when something silent breaks.
* **PR comment warns about missing sessions** — when a commit's trailer references a session that wasn't registered in Chainloop, the PR comment shows a "missing sessions" warning and the `Chainloop AI Policies` check run lists the offending session IDs (the actual Claude or Cursor session IDs). Grep for those IDs in `.git/chainloop-trace/log.txt` on the developer's machine to see why the attestation push didn't land — typically auth failure, network error, or a rejected attestation.
## Open Source vs. Enterprise Edition
`chainloop trace` itself is open source. Against an open-source [Evidence Store](/guides/deployment/oss), a recorded session is a signed piece of evidence like any other: it's captured with full metrics and per-line attribution, redacted of secrets, stored in your own CAS backend, and retrievable through the CLI and API. You can download it, evaluate it with your own [Rego or WASM policies](/guides/custom-policies), and gate the `git push` on the result with [control gates](/concepts/control-gates).
The Enterprise Edition adds what happens once the evidence has landed:
* **A curated policy library.** Instead of only the Rego you write yourself, you get Chainloop's [built-in policies](/concepts/ai-coding-sessions#built-in-policies) for signed commits, agent allowlists, dangerous-command detection, and secret scanning.
* **The session UI and the organization-wide view.** [Rendered session summaries](#visualize-ai-coding-sessions) with attribution drill-down, and the [AI Coding dashboard](#use-the-ai-coding-dashboard) aggregating every session across the org.
* **[Pull request correlation](#pull-request-correlation).** The summary comment, the `Chainloop AI Policies` result on the head commit, missing-session detection, and the [AI Session Score](/reference/ai-score).
| | Open Source | Enterprise Edition |
| ------------------------------------------------------------------------------------------------- | :---------: | :----------------: |
| Recording sessions, attribution, redaction, signed evidence | ✅ | ✅ |
| Your own Rego and WASM policies, and control gates on push | ✅ | ✅ |
| Curated [policy library](/concepts/ai-coding-sessions#built-in-policies) | — | ✅ |
| Session UI and [AI Coding dashboard](#use-the-ai-coding-dashboard) | — | ✅ |
| [Pull request correlation](#pull-request-correlation) and [AI Session Score](/reference/ai-score) | — | ✅ |
Enterprise Edition features are available on [paid plans](https://chainloop.dev/pricing). For the full capability-by-capability breakdown, see [Open Source vs. Platform](/concepts/ai-coding-sessions#open-source-vs-platform).
## Related Resources
* [AI Coding Sessions](/concepts/ai-coding-sessions) — what sessions are, how PR correlation works, and what each dashboard card means
* [Open Source vs. Platform](/concepts/ai-coding-sessions#open-source-vs-platform) — which trace capabilities need a paid plan
* [AI Session Score](/reference/ai-score) — per-PR confidence signal for AI-assisted changes
* [How to collect AI agent configuration](/guides/ai-config-collector) — capture static AI agent configuration files
* [Keyless attestations in GitHub](/guides/github-keyless) — enroll a GitHub repository and link it to a Chainloop project
* [PR-Policies control gate](/guides/pr-policies-control-gate) — enforce pull request quality standards with Chainloop policies
* [Material Types](/concepts/material-types) — full list of supported material types
* [Policies](/concepts/policies) — how policies work in Chainloop
* [How to write custom policies](/guides/custom-policies) — write Rego policies for your evidence