> ## 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.
# AI Sessions Quickstart
> The first link of the agentic SDLC. Record any AI session with Chainloop, govern it with policies as code, and keep signed evidence running from prompt to production.
*This is a beta feature. Expect changes.*
An **AI session** is one piece of work done by an AI agent, with or without a human in the loop: the prompts, the model, the tools and skills it used, the full transcript, and what it produced.
AI sessions are the first step of the **agentic SDLC**, the software development lifecycle now run with agents. Code, specs, reviews and research begin as a conversation with an agent, and that conversation is where the decisions get made. Chainloop records every session as signed evidence, the first link in the same chain as the commit, the build and the release, and runs your policies on each one. Your record runs from **prompt to production**, and so does your governance.
## Why it matters
Every session becomes an attestation: a signed record that anyone can verify later, stored in your cloud or ours. Rules and AI reviewers run on it, to gate what ships and to send findings back to the agent. Think of it as a flight recorder for AI work: complete, tamper-evident, and there when you need to ask what happened. Start with coding sessions today. Every other session your organization runs, PRDs, reviews, security assessments, deployments, lands in the same graph.
More demos at [chainloop.dev/demo](https://chainloop.dev/demo). Product overview at [chainloop.dev/ai-sessions](https://chainloop.dev/ai-sessions).
## Record your first session
This walkthrough uses Chainloop SaaS. Open source users follow the same steps against their own instance. See [How to trace AI coding sessions](/guides/chainloop-trace) for the full guide.
**You will need**
* A git repository you can push to. A small test repository is perfect.
* One of the supported agents installed: Claude Code, Cursor, or OpenCode. See [which agents are supported](#faq).
* A terminal on macOS or Linux.
Go to [app.chainloop.dev](https://app.chainloop.dev/login) and sign up with your business email. Finish the short onboarding: it creates your organization and asks what you want to do. Pick **AI Governance / AI Sessions**.
Do this in the browser before installing anything. The CLI in step 3 will use this account.
In the left sidebar, under **AI Governance**, click **Coding Sessions**. Since you have no sessions yet, the page shows the setup steps and a snippet you can copy. They are the same steps as the ones below.
```bash theme={"dark"}
curl -sfL https://dl.chainloop.dev/cli/install.sh | bash -s
chainloop auth login
```
The second command opens your browser. Sign in with the account you just created and come back to the terminal.
Once per repository, from its root:
```bash theme={"dark"}
cd my-repository
chainloop trace init
```
It asks three questions: your organization, a project to group sessions under (type a name and it is created for you), and which agents to record. Then it installs the hooks.
Ask your agent for any small change, and have it commit and push. With Claude Code:
```bash theme={"dark"}
claude -p "add a greeting message to README, commit and push"
```
With Cursor or OpenCode, open the agent as usual and ask for the same thing. From now on this happens on every push.
When the push finishes, the agent prints the link:
```text theme={"dark"}
Coding Session Available at https://app.chainloop.dev/u/a/sessions/
```
Open it, or refresh **Coding Sessions**. You will see the agent, the model, the tools it called, the messages, and every line it changed.
A general session records one agent run, with or without a repository, and even if nothing was committed. Use it for a PRD, a spec, a review, a research task, or a job in a sandbox.
**You will need**
* One of the supported agents installed. See [which agents are supported](#faq).
* A terminal on macOS or Linux.
Go to [app.chainloop.dev](https://app.chainloop.dev/login) and sign up with your business email. Finish the short onboarding: it creates your organization and asks what you want to do. Pick **AI Governance / AI Sessions**.
```bash theme={"dark"}
curl -sfL https://dl.chainloop.dev/cli/install.sh | bash -s
chainloop auth login
```
Put `chainloop trace run` in front of the command you would normally run. Pass your organization, a project to group sessions under, and a name for this kind of session:
```bash theme={"dark"}
chainloop trace run --org my-org --project my-project --workflow spec-review -- claude -p "review this spec"
```
Chainloop installs the hooks, runs the command, records the session when it exits, and removes everything it installed.
The session appears in Chainloop under **AI Governance**. It carries the agent, the model, the tools it called, and the messages. Without a repository it carries no commit attribution.
General sessions are newer than coding sessions and the flags may still change. See [Record a Single Agent Run](/guides/chainloop-trace#record-a-single-agent-run) for the details.
## Two kinds of session
| | Coding session | General session |
| --------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **What it is** | An agent working in a git repository | Any other agent run: a PRD, a spec, a code review, QA, a security or adversarial review, a research task |
| **Tied to** | The commit, the branch, the exact lines changed, the pull request | The run itself, with or without a repository |
| **How you record it** | Set up the repository once. Every push records automatically. | Wrap the command. The session is recorded when it finishes. |
## Govern every session
Policies run on every session, and they are code. Deterministic ones check facts: no secrets in the transcript, only approved agents, only allowed MCP servers and skills, signed commits. Agentic ones apply judgment: an adversarial security review of a spec, a PRD readout run by a team of agents, a quality score on a pull request. You define them once, at project, team or organization level, and Chainloop applies them to every session that lands.
A session that breaks a rule is rejected, the way a QA session rejects a build that fails its checks. One that falls short comes back with the findings, the way a security review sends a release back to the agent to fix before it ships. That is the **governance loop**: the same policies that gate what ships also steer the agents that produce it, and the results get better with every pass.
## How it works
1. **Hooks capture the session.** While the agent works, hooks in the agent record the model, the tools it calls, and the messages. In a coding session they also snapshot each file before and after every edit, which is what makes per-line attribution possible. Nothing leaves your machine yet.
2. **Push signs and sends it.** When you push, or when a general session's run ends, Chainloop bundles the session, redacts secrets, signs the bundle, and uploads it. Hand-written commits pass through untouched.
3. **Chainloop shows it and gates on it.** The session appears with every line attributed to AI or to a person. Policies run on it. Connected pull requests get a summary and a check.
**Local until you push.** Session data stays in your repository until the push.
**Secrets redacted.** Removed before upload, reported without the value.
**Signed, not logged.** Every session is an attestation you can verify later.
**Open source collector.** You can [read exactly what is captured](https://github.com/chainloop-dev/chainloop).
Under the hood, attestations land in the trusted evidence store next to your builds, scans and SBOMs, and the policy engine evaluates them against Chainloop's curated catalog and your own policies as code. Results surface in the session view, on the pull request, in the dashboard, and through MCP and the API.
## Next steps
* **Share the setup.** Commit `.chainloop.yml` and `.claude/settings.json`. Teammates only install the CLI and log in.
* **Connect your pull requests.** Install the Chainloop GitHub App. Every PR gets the sessions behind it and a policy check. See [Pull Request Correlation](/guides/chainloop-trace#pull-request-correlation).
* **Add rules.** Attach [policies](/reference/policies): approved agents only, no dangerous commands, no secrets, signed commits.
* **Go deeper.** [AI Coding Sessions](/concepts/ai-coding-sessions) explains sessions, pull requests, and the dashboard together.
## FAQ
| Agent | Status |
| ------------------------------------------------------------- | ---------------------------------------------------- |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Supported |
| [OpenCode](https://opencode.ai) | Supported |
| [Cursor](https://cursor.com) | Supported, experimental. No token usage or cost yet. |
| [Codex](https://openai.com/codex/) | Coming. [Talk to us](https://chainloop.dev/contact). |
| [GitHub Copilot](https://github.com/features/copilot) | Coming. [Talk to us](https://chainloop.dev/contact). |
| [Gemini](https://gemini.google.com) | Coming. [Talk to us](https://chainloop.dev/contact). |
| [Windsurf](https://windsurf.com) | Coming. [Talk to us](https://chainloop.dev/contact). |
| [Amp](https://ampcode.com) | Coming. [Talk to us](https://chainloop.dev/contact). |
| [Junie](https://www.jetbrains.com/junie/) | Coming. [Talk to us](https://chainloop.dev/contact). |
| [Droid](https://factory.ai) | Coming. [Talk to us](https://chainloop.dev/contact). |
The collector is open source and built to take new agents. If yours is missing, [contact us](https://chainloop.dev/contact) or open an issue on [GitHub](https://github.com/chainloop-dev/chainloop).
Yes. The collector, the CLI, the control plane, the evidence store and the policy engine are open source under the [Apache 2.0 license](https://github.com/chainloop-dev/chainloop/blob/main/LICENSE.md) at [github.com/chainloop-dev/chainloop](https://github.com/chainloop-dev/chainloop). Recording, signing, storing and applying your own policies work against the open source instance. See [deploying open source Chainloop](/guides/deployment/oss). The session UI, pull request correlation, the dashboard and the curated policy library are part of Chainloop SaaS and on-prem Enterprise. See [Open Source vs. Platform](/concepts/ai-coding-sessions#open-source-vs-platform).
* The agent and its version, when the session started and ended
* The models used, token counts, and estimated cost
* Every tool the agent called and how many times
* The messages exchanged, that is the transcript
* For coding sessions, each file changed with the exact line ranges, attributed to AI or to a person
* The repository, branch and commit range the session belongs to
* What secret redaction did before upload
Yes, after secrets are redacted. The transcript is part of the signed evidence, so policies can run against it today, for example no secrets or no dangerous commands. Next, you will be able to process transcripts, write policies that read them, ask questions across them, and follow a session into the commits, pull requests and releases that came out of it. The same goes for every kind of session, PRDs, specs, reviews, QA, security and adversarial reviews, research: recording them, producing readouts from them, and asking questions across all of them is where this is heading.
Session evidence goes to a Content Addressable Storage backend, either one Chainloop manages or your own OCI registry, S3, GCS or Azure Blob bucket. Everything is referenced by digest, so a session, an SBOM and a build artifact are addressed the same way and cannot be swapped without the digest changing. See [CAS backend](/concepts/cas-backend).
Every session is signed. It is wrapped as an in-toto attestation in a DSSE envelope inside a Sigstore bundle, signed with the mechanism you choose: Sigstore keyless, your own keys, or a KMS. Anyone with the public material can verify it later. Transport is TLS, and at rest the evidence inherits the encryption of the storage backend you picked. See [Attestations](/concepts/attestations) and [Signing](/reference/signing).
For a coding session, yes. The repository is what lets Chainloop attribute every changed line to the agent or to a person, tie the session to the commit and branch, and later connect it to the pull request and the release. For a general session, no. `chainloop trace run` records the run on its own, including the transcript and tool calls, and records it even if nothing was committed.
Two kinds, both written as code and both evaluated on the signed session. **Deterministic** policies check facts: no secrets in the transcript, only approved agents, only allowed MCP servers, only allowed skills, no dangerous commands, signed commits, a token budget, a cap on the AI-authored share of a change. **Agentic** policies apply judgment with an AI reviewer: an adversarial security review of a spec, a PRD readout by a team of agents, a code review against your guidelines, a quality score on a pull request. You define them at project, team or organization level and every session that lands is evaluated the same way.
Chainloop ships [built-in policies for AI sessions](/concepts/ai-coding-sessions#built-in-policies). The [policy reference](/reference/policies) lists every policy and policy group. To write your own in Rego or WASM, start with [Policies](/concepts/policies) and the [WASM policies guide](/guides/wasm-policies/overview). The [trace guide](/guides/chainloop-trace#applying-policies) shows session-specific examples such as a model allowlist and a token budget.
Yes. Chainloop Platform runs review agents in its own sandboxed infrastructure, with access to the session itself, the code it touched, the rest of the evidence graph for that project (scans, SBOMs, provenance, previous releases) and the other sessions stored in your organization. That is more context than a reviewer inside the coding agent has. Findings land on the session and on the pull request as policy results and scores, next to the deterministic checks. [Talk to us](https://chainloop.dev/contact) to enable agentic policies for your organization.
A policy result is not only a verdict, it is feedback. When a session fails or scores low, the findings are attached to the session and surfaced on the pull request, where the agent, or the developer steering it, picks them up and iterates. Because the policies are code and live at project, team or organization level, every agent in the organization is steered by the same guidelines, and every pass through the loop produces a session that is closer to them. Rejection gates what ships. Feedback improves what gets produced next.
That is what a general session plus an agentic policy is for. Record the PRD or spec session, then attach a policy that runs a readout with a team of agents, an adversarial review, or a check against your product guidelines. The result lands on the session, signed, and can be required before the work moves to the next stage.
Use the [Chainloop MCP server](/guides/chainloop-mcp) from your agent or AI client to search and read sessions and the rest of your evidence. A dedicated sessions API is coming. The [control plane and platform APIs](/api-reference/overview) are available today for workflows, runs, policies and projects.
Yes. It is exposed at `https://api.app.chainloop.dev/mcp` with OAuth or API token authentication, and works from Claude Code, Cursor and other MCP clients. See [How to use the Chainloop MCP server](/guides/chainloop-mcp).
No. Once a repository is set up, developers use their agent, commit, and push as before. The hooks do the recording. Nothing is added to the agent's prompt and no extra command is needed.
Only pushes that contain commits from an AI session build an attestation. Other pushes pass through untouched. If recording fails, for example because you are offline, the push still goes through and you see a warning. You can make it strict with `requireTrace` in `.chainloop.yml`. See [Enforcing](/guides/chainloop-trace#enforcing-chainloop-trace).
Nothing until you push. At push time the session is scanned for secrets, the ones found are replaced with placeholders, and only then is the bundle signed and uploaded. The local copy is left untouched. If the scan cannot run, the session is not uploaded. The collector is [open source](https://github.com/chainloop-dev/chainloop), so you can read exactly what is captured.
Commit `.chainloop.yml` and the agent configuration files that `chainloop trace init` created. Each teammate then installs the CLI, logs in, and runs `chainloop trace init` once. It has nothing left to ask them.
Run `chainloop trace uninstall` from the repository root. It removes the git hooks, the agent hooks, and the local session data, and restores any hooks that were there before. See [Removing Tracing](/guides/chainloop-trace#removing-tracing).
Yes. Chainloop runs in production at highly regulated companies, including Fortune 500, as the evidence and policy layer for their software supply chain. AI sessions land in that same system, next to builds, scans and releases.