AI Use Collector
Track AI coding assistant usage across your organization. Collect agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md), plans directories, CI tool invocations, and AI authorship annotations from commits.
ai-use to your lunar-config.yml:uses: github://earthly/lunar-lib/collectors/ai-use@v1.0.0
What This Integration Collects
This integration includes 6 collectors that gather metadata from your systems.
instruction-files
Discovers all agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, CODEX.md) across the repository using a configurable find command. Records each file's path, line count, byte size, markdown section headings, and symlink status. Groups files by directory for per-directory policy checks.
plans-dir
Checks whether a dedicated plans directory exists for AI agent task planning. Tries candidate paths in order (first match wins). Records the directory path and file count.
ai-cli-ci-claude
Detects Claude Code CLI invocations in CI pipelines. Records the command string and version for policy-level flag analysis.
ai-cli-ci-codex
Detects OpenAI Codex CLI invocations in CI pipelines. Records the command string and version for policy-level flag analysis.
ai-cli-ci-gemini
Detects Google Gemini CLI invocations in CI pipelines. Records the command string and version for policy-level flag analysis.
ai-authorship
Collects AI authorship annotation data from commits. Supports the Git AI standard (refs/notes/ai) for line-level tracking and git trailers (AI-model, AI-tokens) as a lightweight fallback. Records annotation coverage across commits in scope.
How Collectors Fit into Lunar
Lunar watches your code and CI/CD systems to collect SDLC data from config files, test results, IaC, deployment configurations, security scans, and more.
Collectors are the automatic data-gathering layer. They extract structured metadata from your repositories and pipelines, feeding it into Lunar's centralized database where guardrails evaluate it to enforce your engineering standards.
Learn How Lunar Works →Example Collected Data
This collector writes structured metadata to the Component JSON. Here's an example of the data it produces:
{
"ai_use": {
"instructions": {
"root": {
"exists": true,
"filename": "AGENTS.md",
"lines": 85,
"bytes": 3200,
"sections": ["Project Overview", "Architecture", "Build Commands", "Testing"]
},
"all": [
{
"path": "AGENTS.md",
"dir": ".",
"filename": "AGENTS.md",
"lines": 85,
"bytes": 3200,
"sections": ["Project Overview", "Architecture", "Build Commands", "Testing"],
"is_symlink": false,
"symlink_target": null
},
{
"path": "CLAUDE.md",
"dir": ".",
"filename": "CLAUDE.md",
"lines": 85,
"bytes": 3200,
"sections": ["Project Overview", "Architecture", "Build Commands", "Testing"],
"is_symlink": true,
"symlink_target": "AGENTS.md"
}
],
"count": 2,
"total_bytes": 3200,
"directories": [
{
"dir": ".",
"files": [
{ "filename": "AGENTS.md", "is_symlink": false },
{ "filename": "CLAUDE.md", "is_symlink": true, "symlink_target": "AGENTS.md" }
]
}
],
"source": { "tool": "find", "integration": "code" }
},
"plans_dir": {
"exists": true,
"path": ".agents/plans",
"file_count": 3
},
"cicd": {
"cmds": [
{
"cmd": "claude -p --output-format json --allowedTools Bash(git*) Read 'review this PR'",
"tool": "claude",
"version": "1.0.20",
"allowed_tools": "Bash(git*) Read"
}
]
},
"authorship": {
"provider": "git-ai",
"total_commits": 12,
"annotated_commits": 8,
"git_ai": {
"notes_ref_exists": true,
"commits_with_notes": 8
}
}
}
}Configuration
Configure this collector in your lunar-config.yml.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
md_find_command
|
Optional |
find . \( -type f -o -type l \) \( -name AGENTS.md -o -name CLAUDE.md -o -name GEMINI.md -o -name CODEX.md \) -not -path '*/node_modules/*' -not -path '*/.git/*'
|
Command to find agent instruction files (must output one file path per line) |
plans_dir_paths
|
Optional |
.agents/plans,.ai/plans
|
Comma-separated list of candidate paths for the plans directory (first match wins) |
annotation_prefix
|
Optional |
AI-
|
Prefix for git trailer-based AI annotations |
default_branch_window
|
Optional |
50
|
Number of recent commits to scan on the default branch |
Documentation
View on GitHubAI Use Collector
Collects AI coding assistant usage data including instruction files, plans directories, CI tool invocations, and authorship annotations.
Overview
This collector tracks how AI coding assistants are used across your repositories and CI pipelines. It discovers agent instruction files (AGENTS.md, CLAUDE.md, etc.), checks for dedicated planning directories, detects AI CLI tools running in CI with their flags, and collects AI authorship annotations from commits via the Git AI standard or git trailers.
Collected Data
This collector writes to the following Component JSON paths:
| Path | Type | Description |
|---|---|---|
.ai_use.instructions |
object | Agent instruction files: root file info, all files with sections/symlink status, per-directory grouping, total byte count |
.ai_use.plans_dir |
object | Plans directory existence, path, and file count |
.ai_use.cicd.cmds[] |
array | AI CLI tool invocations detected in CI: command string, version, and tool/MCP configuration (allowed tools, sandbox mode, approval mode) |
.ai_use.authorship |
object | AI authorship annotation coverage across commits (Git AI notes or git trailers) |
Collectors
This integration provides the following collectors (use include to select a subset):
| Collector | Description |
|---|---|
instruction-files |
Discovers AGENTS.md, CLAUDE.md, GEMINI.md, CODEX.md files with metadata and symlink status |
plans-dir |
Checks for a dedicated AI plans directory |
ai-cli-ci-claude |
Detects Claude Code CLI invocations in CI and flags dangerous permissions |
ai-cli-ci-codex |
Detects OpenAI Codex CLI invocations in CI and flags dangerous permissions |
ai-cli-ci-gemini |
Detects Google Gemini CLI invocations in CI and flags dangerous permissions |
ai-authorship |
Collects AI authorship annotations from commits via Git AI standard or git trailers |
Installation
Add to your lunar-config.yml:
collectors:
- uses: github://earthly/lunar-lib/collectors/ai-use@v1.0.0
on: ["domain:your-domain"] # Or use tags like [backend, go]
# with:
# md_find_command: "find . -type f \\( -name AGENTS.md -o -name CLAUDE.md \\)"
# plans_dir_paths: ".agents/plans,.ai/plans"
# annotation_prefix: "AI-"
# default_branch_window: "50"
Open Source
This collector is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.
Common Use Cases
Explore guardrails that use data from AI Use Collector.
Ready to Automate Your Standards?
See how Lunar can turn your engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.
Infrastructure conventions
Post-mortem action items
Security & compliance policies
Testing & quality requirements