Skip to content

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 origin
  • Co-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: Claude <noreply@anthropic.com>
Generated-by: claude-code

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:

git log --format='%(trailers:key=Generated-by)' --grep='Generated-by'

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 including trailer-exists which can require specific trailers
  • Local plugin API — custom rules can be defined inline in commitlint.config.js without 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 lore CLI 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

Generated-by: <agent-identifier>

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-by provides GitHub UI rendering of the AI contributor
  • Prompted-by links the commit to the human who initiated the work
  • Session-id enables 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:

  1. Warns (level 1) if a commit has a Generated-by trailer with an unrecognized agent identifier
  2. Does not require the trailer on all commits (human commits remain trailer-free)
  3. 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-by trailers 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 --format or 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-by trailer
  • 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.