> ## 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 collect AI agent configuration

> Automatically gather agentic development configuration files as attestation evidence

<Warning>
  This is a preview/beta feature. Further changes are expected.
</Warning>

## Overview

Chainloop can automatically collect AI agent configuration files during the attestation process. This creates a `CHAINLOOP_AI_AGENT_CONFIG` material that captures how agentic development tools are configured in your project, providing visibility and policy enforcement over AI tool usage in your software delivery lifecycle.

The collector currently supports **Claude** configuration files, with support for additional AI agents planned for future releases.

## How it works

When you pass the `--collectors aiagent` flag to `chainloop attestation init`, the CLI scans your project for known AI agent configuration files. The discovered files are bundled into a single `CHAINLOOP_AI_AGENT_CONFIG` material and automatically included in the attestation (no manual `attestation add` step is required).

The collected material includes metadata about the agent, a hash of the overall configuration, timestamps, and details about each discovered file.

### Collected files

The `aiagent` collector currently looks for the following Claude configuration file patterns:

| Pattern                     | Description                   |
| --------------------------- | ----------------------------- |
| `CLAUDE.md`                 | Project-level instructions    |
| `.claude/CLAUDE.md`         | Claude directory instructions |
| `.claude/settings.json`     | Claude settings               |
| `.mcp.json`                 | MCP server configuration      |
| `.claude/rules/*.md`        | Custom rules                  |
| `.claude/agents/*.md`       | Agent definitions             |
| `.claude/commands/*.md`     | Custom commands               |
| `.claude/skills/*/SKILL.md` | Skill definitions             |

<Note>
  Support for additional AI agents beyond Claude will be added in future releases.
</Note>

### Material schema

The `CHAINLOOP_AI_AGENT_CONFIG` material follows this structure:

```json theme={"dark"}
{
  "schema_version": "0.1",
  "agent": {
    "name": "claude"
  },
  "config_hash": "a0b3d547228b5b6e...",
  "captured_at": "2026-03-13T12:04:38Z",
  "config_files": [
    {
      "path": ".claude/settings.json",
      "sha256": "95125ab3c3c69aa1...",
      "size": 258
      ...
    }
  ]
}
```

<Warning>
  The schema version is `0.1` and may evolve as the feature matures. Always include a `valid_input` guard in your policies to handle schema changes gracefully.
</Warning>

## Enabling the collector

<Steps>
  <Step title="Initialize the attestation with the collector">
    Pass the `--collectors aiagent` flag during attestation initialization:

    ```bash theme={"dark"}
    chainloop attestation init \
      --workflow my-workflow \
      --project my-project \
      --collectors aiagent
    ```

    The CLI will scan for AI agent configuration files and report what it found.
  </Step>

  <Step title="Continue the attestation as normal">
    Add any other materials required by your contract and push:

    ```bash theme={"dark"}
    # Add other materials as required by your contract
    chainloop attestation add --value my-image:latest

    # Push the attestation — the AI config material is included automatically
    chainloop attestation push
    ```
  </Step>
</Steps>

<Tip>
  The collector works alongside any other materials defined in your contract. You can combine it with SBOMs, container images, and any other evidence types.
</Tip>

## Contract example

While the collector automatically attaches the material, defining `CHAINLOOP_AI_AGENT_CONFIG` in your contract allows you to attach policies to it:

```yaml contract.yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: ai-config-example
spec:
  materials:
    - type: CONTAINER_IMAGE
      name: my-app
      output: true
    - type: CHAINLOOP_AI_AGENT_CONFIG
      name: ai-agent-config
  policies:
    materials:
      - ref: file://check-agent-name.yaml
```

## Built-in policies

Chainloop ships with built-in [policies](/reference/policies) for AI agent configuration governance. Attach them to your contract to start enforcing best practices immediately — no custom Rego required:

| Policy                                       | What it checks                                                               |
| -------------------------------------------- | ---------------------------------------------------------------------------- |
| `ai-agent-present`                           | Detect AI agent presence via configuration materials or bot reviewers on PRs |
| `ai-config-mcp-servers-allowed`              | Ensure only approved MCP integrations are configured                         |
| `ai-config-architecture-with-paths`          | Verify instruction files describe project architecture                       |
| `ai-config-code-style-specificity`           | Require concrete, project-specific code style rules                          |
| `ai-config-skill-descriptions-actionable`    | Ensure skills describe what they do and when to use them                     |
| `ai-config-subagent-descriptions-actionable` | Require subagent descriptions with trigger, scope, and purpose               |
| `ai-instructions-commands-documented`        | Require exact, executable commands instead of vague instructions             |
| `ai-instructions-size-bounds`                | Enforce line count limits on instruction and skill files                     |
| `ai-instructions-verification-criteria`      | Require verification mechanisms like tests or expected outputs               |

To use a built-in policy, reference it by name in your contract:

```yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: ai-governance
spec:
  materials:
    - type: CHAINLOOP_AI_AGENT_CONFIG
      name: ai-agent-config
  policies:
    materials:
      - ref: ai-config-mcp-servers-allowed
        with:
          allowed_servers: "github,slack,linear"
```

## Writing a custom policy

You can also write custom [Rego policies](/guides/custom-policies) to enforce rules on the collected AI configuration. The following example checks that the agent name is `claude` and produces a violation otherwise.

```yaml check-agent-name.yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Policy
metadata:
  name: check-agent-name
  description: Validates that the AI agent configuration is from an approved agent
spec:
  policies:
    - kind: CHAINLOOP_AI_AGENT_CONFIG
      embedded: |
        package main

        import rego.v1

        valid_input if {
          input.agent.name
        }

        violations contains msg if {
          valid_input
          input.agent.name != "claude"
          msg := sprintf("AI agent '%s' is not approved. Only 'claude' is allowed.", [input.agent.name])
        }
```

The policy works as follows:

* `valid_input` checks that the material contains an `agent.name` field, skipping evaluation if the schema is unexpected.
* The `violations` rule fires when `agent.name` is anything other than `"claude"`, producing a descriptive error message.

This pattern can be extended to check other fields in the AI config, such as verifying specific config files are present or that the configuration hash matches an expected value.

## Testing the policy locally

Use the [policy development CLI tools](/guides/custom-policies#getting-started-with-policy-development-cli-tools) to validate your policy before deploying it:

```bash theme={"dark"}
# Lint the policy
chainloop policy develop lint --policy check-agent-name.yaml

# Evaluate against a sample AI config material
chainloop policy develop eval \
  --policy check-agent-name.yaml \
  --material sample-ai-config.json \
  --kind CHAINLOOP_AI_AGENT_CONFIG
```

## Related resources

* [Material Types](/concepts/material-types) — Full list of supported material types
* [How to write custom policies](/guides/custom-policies) — In-depth guide on writing and testing Rego policies
* [Policies concept](/concepts/policies) — How policies work in Chainloop