Commitlint conventions for AI agent git history tracking¶
- Date: 2026-03-24
- Status: Accepted
- Tags:
tooling|workflow|process
Context¶
AI coding agents (Claude Code, Cursor, Windsurf, Copilot) now routinely create git commits on behalf of developers. As agent-authored commits grow in proportion, the ability to distinguish human from AI commits — and to identify which agent authored a change — becomes critical for auditing, changelog generation, blame analysis, and incident response.
No industry standard yet exists for AI commit attribution. The Conventional
Commits specification defines type(scope): description plus footer
trailers, but says nothing about authorship provenance. Meanwhile, tools
like Dependabot and Renovate have established bot-specific patterns (custom
committer identities, [bot] suffixes, configurable commit prefixes) that
serve as prior art but were designed for narrow automation, not general
agentic coding.
This ADR documents research into the commitlint ecosystem, git trailer conventions, and emerging practices across AI coding tools, and recommends a convention for this repository and its connected projects.
Research Findings¶
1. Conventional Commits extension points¶
The Conventional Commits 1.0.0 spec provides three natural extension points for AI attribution:
| Extension point | Example | Pros | Cons |
|---|---|---|---|
| Custom type | ai-fix(auth): ... |
Visible in log at a glance | Breaks standard type enums; tools that filter on fix/feat miss these commits |
| Scope annotation | fix(auth/ai): ... |
Preserves standard types | Overloads scope semantics; makes scope filtering noisy |
| Footer trailers | Generated-by: claude-code |
Non-breaking; machine-parseable; unlimited metadata | Not visible in one-line log; requires trailer-aware tooling |
Recommendation: Footer trailers are the correct layer. They carry structured metadata without disrupting type/scope semantics that changelogs, release-please, and semantic-release depend on.
2. Git trailer conventions¶
Git natively supports trailers via git interpret-trailers and
git log --format='%(trailers)'. Key established trailers:
Signed-off-by:— DCO certification of originCo-authored-by:— multi-author attribution (GitHub renders these)Reviewed-by:— code review acknowledgment
GitHub specifically renders Co-authored-by trailers in the commit UI,
linking to contributor profiles. This is the only trailer with broad
platform-level rendering support.
For AI agents, two trailer patterns are emerging in practice:
Co-authored-by leverages GitHub's existing rendering but implies the AI
is a peer author. A dedicated Generated-by (or AI-Generated-by)
trailer is more semantically accurate and enables clean filtering:
3. Commitlint plugin ecosystem¶
The official @commitlint monorepo provides:
@commitlint/config-conventional— enforces standard Conventional Commits types (feat,fix,chore, etc.)@commitlint/rules— built-in rules includingtrailer-existswhich can require specific trailers- Local plugin API — custom rules can be defined inline in
commitlint.config.jswithout publishing a package
A local plugin can enforce AI attribution trailers:
// commitlint.config.js
export default {
extends: ['@commitlint/config-conventional'],
plugins: [
{
rules: {
'ai-trailer-format': ({ raw }) => {
const generatedBy = raw.match(/^Generated-by:\s*(.+)$/m);
if (!generatedBy) return [true]; // not AI-authored, skip
const validAgents = [
'claude-code', 'cursor', 'windsurf', 'copilot', 'gemini'
];
return [
validAgents.includes(generatedBy[1].trim()),
`Generated-by must be one of: ${validAgents.join(', ')}`,
];
},
},
},
],
rules: {
'ai-trailer-format': [1, 'always'], // warn level
},
};
There are no published commitlint plugins specifically for AI agent
attribution as of March 2026. The commitlint-plugin-function-rules
community package enables dynamic rule functions but is unnecessary
given the built-in local plugin API.
4. How existing bots handle attribution¶
| Tool | Committer identity | Commit message pattern | Trailers |
|---|---|---|---|
| Dependabot | dependabot[bot] |
chore(deps): bump X from A to B |
Signed-off-by: dependabot[bot] |
| Renovate | Configurable (default: renovate[bot]) |
Configurable; default chore(deps): update X |
Optional via commitBody config |
| GitHub Actions | github-actions[bot] |
Varies by workflow | None standard |
| Claude Code | User's git identity | Standard Conventional Commits | Co-authored-by (configurable via settings.json attribution) |
| Aider | User's git identity (with optional (aider) suffix) |
Standard messages | Co-authored-by: aider (<model>) <noreply@aider.dev> |
| Cursor | User's git identity | Varies | None |
| Copilot | User's git identity | Varies | None |
Key observation: dedicated bots (Dependabot, Renovate) use distinct
committer identities ([bot] suffix), making attribution trivial via
git log --author. AI coding agents operate under the developer's own
git identity, making trailer-based attribution the only reliable
mechanism. Aider is the most advanced here — it includes the model name
in its Co-authored-by trailer and optionally modifies the author name.
5. Changelog and release tooling compatibility¶
- semantic-release / commit-analyzer: Parses Conventional Commits
types and scopes for release decisions. Trailers are ignored by default
but can be accessed via custom
parserOpts. Adding trailers does not break existing release pipelines. - release-please: Parses Conventional Commits for changelog generation. Footer trailers pass through to changelogs if configured but do not interfere with version bumping logic.
- changelogen / conventional-changelog: Same trailer-transparent behavior.
Trailers are the safest extension point — they are invisible to tools that do not look for them and available to tools that do.
6. The Lore protocol — structured decision context in trailers¶
A March 2026 research paper, "Lore: Repurposing Git Commit Messages as a Structured Knowledge Protocol for AI Coding Agents", proposes a two-layer protocol built entirely on git trailers:
- Layer A (format): A vocabulary of standardized trailers —
Constraint:,Rejected:,Confidence:,Scope-risk:,Reversibility:,Directive:,Tested:,Not-tested:,Related:— appended to conventional commit messages. All are optional and the format is extensible (unknown keys are ignored). - Layer B (CLI): An optional
loreCLI for querying and authoring trailers (e.g.,lore context <path>,lore constraints <path>).
Lore's key insight is that commit messages should describe why (not
what) and trailers should carry machine-parseable decision context.
This aligns with our approach: the Generated-by trailer is one layer
of metadata; Lore-style trailers could supplement it for richer
provenance. Lore is not yet widely adopted but validates the trailer-
first direction.
7. Git notes vs. trailers for supplementary metadata¶
Git notes (refs/notes/) allow annotating commits after the fact
without changing their SHA. We evaluated them as a mechanism for richer
AI metadata (model version, full session logs, prompt context).
| Aspect | Git trailers | Git notes |
|---|---|---|
| Timing | Must be added at commit time | Can be added or modified after the fact |
| Commit hash | Part of the hash (immutable) | Stored separately; does not change hash |
| Visibility | Always present in git log |
Requires --notes flag or explicit fetch config |
| Forge support | Good (Co-authored-by rendered on GitHub) |
Poor (GitHub/GitLab do not display notes) |
| Fetch/push | Automatic with commits | Requires explicit refspec (refs/notes/*) |
| Mutability | Immutable once committed | Editable; only one note per object per namespace |
Verdict: Trailers are the primary mechanism. Git notes are not recommended for core attribution because they are invisible on GitHub, not fetched by default, and risk being silently lost during clones and CI. However, notes remain viable for supplementary post-hoc metadata in local workflows — e.g., attaching debugging context or deployment timestamps to commits after the fact. If a team wants richer metadata than trailers can carry, a better path is linking to external systems (Linear issue URLs, session logs) via trailers rather than embedding that data in git notes.
8. Commitlint trailer-exists built-in rule¶
The @commitlint/rules package includes a trailer-exists rule that
shells out to git interpret-trailers --parse to validate trailer
presence. Configuration:
// Require Signed-off-by on all commits
rules: {
'trailer-exists': [2, 'always', 'Signed-off-by:']
}
This rule is useful for enforcing mandatory trailers (like DCO
sign-off) but is too blunt for AI attribution — it would require the
trailer on every commit, including human-authored ones. A local plugin
(see Section 3) that conditionally validates Generated-by only when
present is the better approach.
Decision¶
We will adopt the following conventions for AI-agent-authored commits
across this repository and recommend them for connected projects
(lifeos-agents, trusty_terraform, etc.):
Required trailers for agent-authored commits¶
Where <agent-identifier> is one of: claude-code, cursor,
windsurf, copilot, gemini-code-assist, or another lowercase
kebab-case tool name.
Optional supplementary trailers¶
Co-authored-by: <Agent Name> <noreply@vendor.com>
Prompted-by: <human who triggered the agent>
Session-id: <agent session identifier>
Co-authored-byprovides GitHub UI rendering of the AI contributorPrompted-bylinks the commit to the human who initiated the workSession-idenables tracing back to the agent session for debugging
Commit message structure (unchanged)¶
Standard Conventional Commits types and scopes remain unchanged. AI
agents should use the same feat, fix, docs, chore, etc. types
as human authors. The commit message describes what changed; the
trailers describe who/how.
Commitlint enforcement¶
Add a local commitlint plugin that:
- Warns (level 1) if a commit has a
Generated-bytrailer with an unrecognized agent identifier - Does not require the trailer on all commits (human commits remain trailer-free)
- Validates trailer format (
key: value, no leading whitespace in key)
Git configuration for agents¶
Agent environments (e.g., Cyrus) should configure trailer generation:
git config trailer.generatedby.key "Generated-by"
git config trailer.generatedby.ifmissing add
git config trailer.generatedby.cmd 'echo "claude-code"'
This auto-appends the trailer when git interpret-trailers is invoked,
or agents can append it directly to commit messages.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
Custom commit types (ai-feat, ai-fix) |
Breaks Conventional Commits type enums; invisible to standard changelog tools; mixes authorship concern into semantic versioning signal |
Scope-based annotation (fix(auth/ai)) |
Overloads scope with authorship metadata; makes scope filtering unreliable; no standard parsing support |
Separate committer identity (cyrus[bot]) |
Requires bot GitHub accounts and GPG keys; git blame attributes to bot not human; complicates DCO sign-off chains |
Branch naming convention only (ai/feat-*) |
Lost after merge; no per-commit granularity; branches are ephemeral |
Commit message prefix ([AI]) |
Non-standard; breaks Conventional Commits parsing; not machine-parseable without regex |
| Git notes for AI metadata | Not fetched by default; invisible on GitHub/GitLab; risk of silent loss; one note per object per namespace limits extensibility |
| Full Lore protocol adoption | Promising but pre-1.0; vocabulary is oriented toward decision context, not attribution; adopting the full trailer vocabulary is premature — but the Generated-by approach is compatible with Lore and could layer on top later |
Co-authored-by only (no Generated-by) |
GitHub renders it, but cannot distinguish AI-authored from human-pair-programmed commits; no structured agent identifier; filtering requires regex on free-text name field |
| No convention (status quo) | AI commits are indistinguishable from human commits; no auditability; cannot filter or report on agent activity |
Consequences¶
Positive:
- AI-authored commits are identifiable via
git log --format='%(trailers:key=Generated-by)' - Standard Conventional Commits tooling (semantic-release, release-please, changelogs) continues to work unmodified
- GitHub renders
Co-authored-bytrailers in the commit UI, giving visual attribution - Convention is forward-compatible — new agents just add their identifier to the allowed list
- Trailer-based approach aligns with kernel/DCO precedent for structured commit metadata
Negative / Trade-offs:
- Trailers are not visible in
git log --oneline; requires--formator full log to see attribution - Enforcement depends on commitlint being configured in each repo
- AI tools must be configured or instructed to append trailers; no tool does this by default today
Ongoing obligations:
- Maintain the allowed agent identifier list as new tools are adopted
- Configure Cyrus and other agent environments to auto-append the
Generated-bytrailer - Document the convention in CLAUDE.md files for repos that adopt it
- Periodically review whether platform-level support (GitHub, GitLab) has emerged that supersedes this approach
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.