How to record 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 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 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. The policy library, the session UI, and pull request correlation come with the Enterprise Edition. See Open Source vs. Enterprise Edition at the end of this guide for the split. To keep sessions on your machine with no Chainloop instance at all, see Record Sessions Locally.

​

Two Ways to Record

	In your repository	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:
  curl -sfL https://dl.chainloop.dev/cli/install.sh | bash -s
  chainloop auth login
  
  Local mode needs the CLI but no 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 for the full set of options. Both user tokens and service accounts work.
• A Chainloop project to associate sessions with — chainloop trace init offers to create one if you don’t have it yet.
• A Git repository with one of the supported agents configured: Claude Code, Codex, Cursor, or OpenCode.

chainloop trace supports Claude Code, Codex, 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:

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, .codex/hooks.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. For example, use chainloop trace init --codex to install Codex hooks. If you use Codex, review and trust the installed hooks in Codex before starting work. See the 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. chainloop trace init runs once per repository. Contributors don’t run it. After you commit those files, they work as usual, and the first traced session in their clone installs the git hooks. They only need the Chainloop CLI installed and authenticated.

​

Work as Usual

Once initialized, there’s nothing else to do. Write code with your agent, commit, and push.

# 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.

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.

Running agents in Docker Sandboxes? Chainloop publishes a sandbox kit that wires this up for you, so a session inside the sandbox is recorded as signed evidence — see How to record AI coding sessions in a Docker Sandbox.

	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 traceRequired	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. The session UI, pull request correlation, and the AI Coding dashboard that follow are Enterprise Edition features — see Open Source vs. Enterprise Edition.

​

Capture the Context of a Session

Specs, tasks, skills and screenshots are the inputs of the code. chainloop trace records them with each session, so a reviewer can compare what the agent was asked to build with what it built. Chainloop fetches nothing. The agent writes the text of each source, so there are no connectors or credentials to set up.

• Specs, tasks and plans. At session start, chainloop trace tells the agent to capture what the session works from. That is a ticket, a design document, a spec file, or a plan that you approved in the plan mode of the agent. The agent writes one file per source into .chainloop/specs/<session-id>/ and tells you in one line when it captures a file. At each prompt, chainloop trace reminds the agent to capture a new or changed source. The agent does not capture an agreement in the chat as a plan.
• Role, title and description. The agent gives each source a role (task, spec, plan or reference), a title and a description. The platform uses them to group and name the sources.
• Local files. When a source is a file on disk, the agent records only its path. Each push reads the file and records its current content, so the evidence never holds a stale copy.
• Skills. The evidence lists the skills that the agent loaded, with the SKILL.md and a .tar.gz package of the skill folder as it ran.
• Pasted images. chainloop trace stores each distinct image that you paste into the session once.

On git push, the CLI redacts the sources, stores them as evidence of the session and signs them with the transcript, so an edit to a source breaks the signature. The CLI also replaces exact copies of a source or an image in the transcript with a pointer to its evidence, so the evidence holds each one once. The .chainloop/specs/ folder ignores itself, so git never commits a captured source, and the session end deletes the folder.

Spec capture works with every supported agent. chainloop trace records skills for Claude Code, Codex and OpenCode, not yet for Cursor. Transcript pointers and pasted images work for Claude Code and Codex.

The AI Session Score uses the captured specs to grade the session against what it was asked to do.

​

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.

​

Context Tab

The session page in the AI Coding section has a Context tab. A list on the left groups the captured sources (tasks, specs and plans, attachments, and skills) next to the full transcript, and a detail pane shows each one. The pane renders Markdown, Mermaid diagrams and images. In the transcript, each captured source and image appears where it entered the conversation.

​

Lineage Tab

The Lineage tab follows the code of the session to production. It shows the pull requests and their scans, the workflows on the merge commit, the artifacts they produced, their deployments, and their findings. See Session Lineage for what each column shows.

​

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 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 for both flows. If your repository is already enrolled — for keyless attestations, 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, 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, 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 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 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/<your-org>/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.

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 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.

contract.yaml

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

check-approved-models.yaml

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

check-token-budget.yaml

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

check-ai-code-ratio.yaml

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 traceRequired: 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. In local mode, it blocks the push when the session can’t be stored on disk.

.chainloop.yml

projectName: my-project
organization: acme-corp
traceRequired: true

traceRequired replaces requireTrace, which still works in an older .chainloop.yml but is deprecated. 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 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 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 fails when any referenced session is missing — typically because its push failed and was never retried. This catches the case where traceRequired 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:

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. It keeps the local-sessions folder that local mode writes. 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:
  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 agent 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, 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, and gate the git push on the result with 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 for signed commits, agent allowlists, dangerous-command detection, and secret scanning.
• The session UI and the organization-wide view. Rendered session summaries with attribution drill-down, session lineage to production, and the AI Coding dashboard aggregating every session across the org.
• Pull request correlation. The summary comment, the Chainloop AI Policies result on the head commit, missing-session detection, and the AI Session 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	—	✅
Session UI, session lineage, and AI Coding dashboard	—	✅
Pull request correlation and AI Session Score	—	✅

Enterprise Edition features are available on paid plans. For the full capability-by-capability breakdown, see Open Source vs. Platform.

​

Record Sessions Locally

Everything above sends sessions to a Chainloop instance. Local mode keeps them on your machine instead: no control plane, no account, no login, and no workflow. Use it to evaluate chainloop trace, on a machine that can’t reach Chainloop, or when session data must not leave the machine. The agent still calls its model over the network as usual. Only the traffic to Chainloop stops.

​

Set Up a Repository in Local Mode

Run this once from your repository root:

chainloop trace init --local

It installs the same agent and git hooks as chainloop trace init, but it creates no workflow and doesn’t connect to a control plane. It writes the storage mode to .chainloop.yml:

.chainloop.yml

traceStorage: LOCAL
tracePath: .git/chainloop-trace # optional, this is the default

tracePath is optional. It defaults to .git/chainloop-trace.

Commit .chainloop.yml and the agent configuration files. The storage mode is a repository setting, so every clone records sessions locally. As in any traced repository, contributors don’t run trace init, and in local mode they don’t log in either.

​

Push as Usual

Start the agent, commit, and push. When a session starts, chainloop trace tells the agent that the session is in local mode and where it will be stored. On git push, the pre-push hook builds the same evidence that a push to Chainloop uploads. It redacts secrets and writes the evidence to disk instead of sending an attestation:

INF AI coding session evidence stored at <repo>/.git/chainloop-trace/local-sessions sessions=1

Each session gets its own folder under local-sessions:

.git/chainloop-trace/local-sessions/<session-id>/statement.json
.git/chainloop-trace/local-sessions/<session-id>/evidence/sha256-<digest>

• statement.json is the in-toto statement a push would sign, with the Chainloop predicate (chainloop.dev/attestation/v0.2). It lists every material by name, type, and digest, so you can read the whole session from it.
• evidence/ holds each material, named by its content digest, as the CAS backend addresses them. The materials are the session record, the transcript, spec sources, skills, and pasted images.

​

Record a Single Run Locally

chainloop trace run has the same mode. With --local, it rejects --org, --project, and --workflow. It writes the session to disk when the command exits, also when the command fails:

chainloop trace run --local -- claude -p "fix the failing tests"

trace run doesn’t read traceStorage from .chainloop.yml, so --local is always explicit. The one value it does take from .chainloop.yml is tracePath.

​

What Local Mode Doesn’t Do

• Sessions aren’t signed. statement.json has no envelope and no signature, so it is not an attestation and nothing can verify it. Treat it as a working copy of the session, not as proof.
• No policies, UI, or pull request correlation. Those run on a Chainloop instance. Set traceStorage back to CONTROL_PLANE (or remove it) to attest sessions to an open-source or Enterprise instance.
• Pushes aren’t blocked by default. If a session can’t be stored, the push proceeds with a warning, unless traceRequired is set.

Secret redaction is on by default, as in a push. Set CHAINLOOP_TRACE_NO_REDACT to turn it off. The stored files can then hold secrets, so use it only for a trusted local store.

​

Related Resources

• AI Coding Sessions — what sessions are, how PR correlation works, and what each dashboard card means
• Open Source vs. Platform — which trace capabilities need a paid plan
• AI Session Score — per-PR confidence signal for AI-assisted changes
• How to record AI coding sessions in a Docker Sandbox — record sessions from agents running in an ephemeral sandbox
• How to collect AI agent configuration — capture static AI agent configuration files
• Keyless attestations in GitHub — enroll a GitHub repository and link it to a Chainloop project
• PR-Policies control gate — enforce pull request quality standards with Chainloop policies
• Material Types — full list of supported material types
• Policies — how policies work in Chainloop
• How to write custom policies — write Rego policies for your evidence