How to collect AI agent configuration - Chainloop Documentation

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

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 aiconfig 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 material is named ai-agent-config-<agent> after the agent that was discovered — for example, ai-agent-config-claude for Claude configuration files. The collected material includes metadata about the agent, a hash of the overall configuration, timestamps, and details about each discovered file.

Collected files

The aiconfig 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

Support for additional AI agents beyond Claude will be added in future releases.

Material schema

The CHAINLOOP_AI_AGENT_CONFIG material follows this structure:

{
  "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
      ...
    }
  ]
}

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.

Enabling the collector

Initialize the attestation with the collector

Pass the --collectors aiconfig flag during attestation initialization:

chainloop attestation init \
  --workflow my-workflow \
  --project my-project \
  --collectors aiconfig

The CLI will scan for AI agent configuration files and report what it found.

Continue the attestation as normal

Add any other materials required by your contract and push:

# 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

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

Contract example

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

contract.yaml

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-claude
  policies:
    materials:
      - ref: file://check-agent-name.yaml

The material name in the contract must match the name generated by the collector, ai-agent-config-<agent> (e.g. ai-agent-config-claude). If the names differ, Chainloop treats the contract material as never provided and the attestation fails with a “missing material” error.

Built-in policies

Chainloop ships with built-in 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:

apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: ai-governance
spec:
  materials:
    - type: CHAINLOOP_AI_AGENT_CONFIG
      name: ai-agent-config-claude
  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 to enforce rules on the collected AI configuration. The following example checks that the agent name is claude and produces a violation otherwise.

check-agent-name.yaml

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 to validate your policy before deploying it:

# 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

Material Types — Full list of supported material types
How to write custom policies — In-depth guide on writing and testing Rego policies
Policies concept — How policies work in Chainloop

​Overview

​How it works

​Collected files

​Material schema

​Enabling the collector

​Contract example

​Built-in policies

​Writing a custom policy

​Testing the policy locally

​Related resources

Overview

How it works

Collected files

Material schema

Enabling the collector

Contract example

Built-in policies

Writing a custom policy

Testing the policy locally

Related resources