AI attribution
Know which AI coding tools a repository is set up for (Copilot, Cursor, Claude Code, Codex, Windsurf, Aider and others), which commits declare that a tool took part, and how that changes over time, without pretending to know more than the marks say.
Everything here is a declaration or a set-up, each with a confidence and its evidence. A commit with no mark is “no declared AI involvement”, never “written by a person”: use that leaves no trace is not seen, so every share below is a lower bound.
Before you start
Section titled “Before you start”- For local history, use a Keryn CLI build that supports
keryn attribution --helpand a Git work tree. - Nothing leaves your machine. The CLI reads file paths, the text of small source files, and the local
git log(author, committer, date, message, notes). A path-scoped policy also reads the names of changed files. The local attribution command does not read patch contents or send data.
10-minute demo
Section titled “10-minute demo”Use Git, jq, and an attribution-capable Keryn CLI build. Check your CLI before creating the demo repository.
keryn attribution --helpIf the command reports “unknown command”, your build predates CLI attribution. The released CLI 0.5.2 predates it. You can still read the recorded result below or try attribution in Keryn Web.
In an empty working directory, the commands create a repository with two synthetic commits. The repository has no remote, and the report stays on your machine.
mkdir attribution-demogit init -q -b main attribution-demogit -C attribution-demo config user.name 'Demo Developer'git -C attribution-demo config user.email 'developer@example.invalid'git -C attribution-demo config commit.gpgsign falseprintf 'Example repository for AI attribution.\n' > attribution-demo/README.mdgit -C attribution-demo add README.mdgit -C attribution-demo commit -qm 'Start the demo'printf 'Review generated changes before merging.\n' > attribution-demo/CLAUDE.mdgit -C attribution-demo add CLAUDE.mdgit -C attribution-demo commit -qm 'Add repository instructions' -m 'Co-authored-by: Claude <noreply@anthropic.com>'keryn attribution scan attribution-demo --report demo-attribution.jsonThe recorded result from the demo report is:
jq -c '{commits: .repo.commits, declared: .repo.declared, configured: (.configured | length), developer_rows: (.developers // [] | length)}' demo-attribution.json{"commits":2,"declared":1,"configured":1,"developer_rows":0}One of two commits declares Claude Code assistance. The report should also show that the tree has Claude Code instructions. The first commit has no declared assistance, and there are no developer rows by default.
Try your repositories in Keryn Web
Section titled “Try your repositories in Keryn Web”- Open Organizations in Keryn Web and select the repositories to scan.
- Open the organization dashboard and find AI coding tools across the organization to see tool setup.
- For GitHub repositories, choose Read commit history to see aggregate declarations. The app shows the request estimate before the read.
1. Run it
Section titled “1. Run it”keryn attribution scan . --report attribution.jsonThe summary prints the commits read, how many declare AI involvement (and what share of people’s commits that is, as a lower bound), a row per tool with how many of those commits are high and medium confidence, the tools the tree is set up for, and a series by month. --since 6.months limits the history; --max-commits caps it (20,000 by default, newest first).
The default gate ignores INFO observations from repository setup and commit history. AI usage policy violations are ERROR findings and fail the default gate. Both appear in scan outputs such as --sarif, --json and --annotations.
A plain keryn scan also reports the tree signals (rules files, instruction files, tool configuration) and lists the tools as services in the AI-BOM and as nodes on the trust map. It does not read history.
2. How to read a confidence
Section titled “2. How to read a confidence”| Level | Means | Examples |
|---|---|---|
| high | the tool or its platform writes it itself and a person has no reason to type it | an agent’s own account (copilot-swe-agent[bot], claude[bot], cursoragent@cursor.com); the footer Co-Authored-By: Claude <noreply@anthropic.com>; a Claude-Session: link; aider’s (aider) author suffix; aider’s chat history file |
| medium | a person or a platform set it up on purpose, or said it in their own words | a rules file such as .cursor/rules/*.mdc or CLAUDE.md; a branch prefix such as codex/; “AI disclosure: Codex wrote the test”; a review bot as co-author |
| low | it fits, and fits many other things | a bare name in a co-author line (a person can be called Claude); an account that also runs release automation |
Two independent signals at medium or better (a trailer and a signature line, a branch name and a link in a pull request) corroborate each other to high. Low signals are reported and never counted. Dependency bots, merge queues and release robots are automation, not AI, and are left out of the share.
Three things a number does not say:
- How much code a tool wrote. A declaration says a tool took part. One editor setting adds a
Co-authored-by: Copilottrailer to half the commits of a project without saying how much Copilot wrote. - That the declaration is true. Anyone can type a trailer.
- That a configuration file means use.
CLAUDE.mdshows the repository is set up for a tool, not that it wrote anything.
3. By repository, by developer, by organisation
Section titled “3. By repository, by developer, by organisation”A repository is the default unit. Add --bucket week for a weekly series.
An organisation report combines saved reports from several repositories. From the same directory you used for the demo, create a second synthetic repository with one commit and no declaration. Then combine its report with demo-attribution.json.
git init -q -b main attribution-demo-apigit -C attribution-demo-api -c user.name='Demo Developer' -c user.email=developer@example.invalid \ -c commit.gpgsign=false commit --allow-empty -qm 'Start the demo API'keryn attribution scan attribution-demo-api --report demo-api-attribution.jsonkeryn attribution org demo-attribution.json demo-api-attribution.json --report org.jsonThe saved organisation report contains both repository rows:
jq '.repos | length' org.json2In Keryn Web, an organization scan shows the same roll-up under “AI coding tools across the organization” on the organization dashboard. The tools set up in each repository come from the scans you already ran, so that part makes no request. “Read commit history” then reads each GitHub repository’s commit metadata from api.github.com in your browser, one repository after another. Before you start, it says how many repositories it will read and about how many requests that takes. You can stop it at any time, and a partial result says how many repositories were read. Without a GitHub token, it reads as many repositories as fit in the hourly allowance; with a token, up to 100. The totals are the ones keryn attribution org gives for the same commits. The web view shows totals per repository and for the organization only, never developers. Bitbucket and other repositories outside GitHub.com show the tools set up, not history.
Developer rows are sensitive and off by default. --developers aliases adds a row per commit identity under a keyed-hash alias (dev-3fa91c07); --developers identities adds name and email. Use --salt (one per organisation) so a person keeps the same alias in every repository. An alias hides a name from a reader of the report; it is not anonymisation. Share these rows with administrators only. Automation accounts are never developer rows.
The hosted API enforces the same rule: POST /api/v1/ai-attribution returns the aggregate to any credential with scans:create, and per-developer rows only to organization administrators signed in as people (API keys and members get 403). It takes commit metadata and returns the report without storing it. Metering stays in shadow mode and identical inputs rate at zero. An opted-in webhook can receive an event with the result’s surface hash. See the tested SDK example and v1 compatibility policy and the hosted MCP tool.
4. What it detects
Section titled “4. What it detects”keryn attribution rules prints every rule with its tool, channel and confidence (174 rules, 38 tools).
- The tree: rules, instruction, configuration, ignore and MCP files of Copilot, Cursor, Claude Code, Codex, Windsurf, Aider, Gemini, Cline, Roo Code, Continue, Amazon Q, Kiro, JetBrains Junie, OpenHands, Devin and others, the shared
AGENTS.md, and a source file’s own “generated by” comment. A file in a test or example folder is demoted a level; vendored code is skipped. - Commits: agent accounts,
Co-authored-byandAssisted-bytrailers, signature lines tools write, disclosure lines contribution templates ask for (“LLM involvement: …”; “none” is an answer), merges from agent branches, and Git AI notes (refs/notes/ai). - Pull requests (hosted API and browser): author account, branch prefix, label and body.
5. How accurate it is
Section titled “5. How accurate it is”Measured on 26 repositories and 301,333 commits, with a hand-labelled sample: the hits it counts (high and medium) were true declarations in 69 of 70 judged (98.6%, 95% interval 92.3% to 99.7%; 93.2% before one fix made from that sample), it found about 97% of the declarations a person can read in commit metadata on a held-out sample, and it made no false declaration in 299,053 commits that predate the tools. Pull-request signals were scored separately on 80 hits from real pull requests in 10 public repositories. Those it counts were true declarations in 78 of 79 judged (98.7%, 95% interval 93.2% to 99.8%). Six of those declare AI help with the pull-request text only, not the change; scored as wrong, the figure is 91.1%. A second reviewer labelled the commit sample again without seeing the first labels and agreed on 84 of 88 (Cohen’s kappa 0.82). Both reviewers were AI agents. Silent use is not measured and cannot be: nothing marks it. The full method, the labels and the limits are in the evaluation document of the Keryn repository.
6. Where it shows
Section titled “6. Where it shows”| Where | What |
|---|---|
| Keryn Web results | an “AI attribution” card: tools the repository is set up for, and, for a GitHub repository, the commit history read in your browser on request; nothing goes to Keryn |
| Keryn Web organization | “AI coding tools across the organization”: tools set up per repository and repositories per tool, and, on request, declared commits per repository and in total for the GitHub repositories; aggregate only |
| AI-BOM | a service per configured tool (category ai-coding-tool) with its files as occurrences |
| Trust map | a node per tool, “(AI coding tool)” |
| MCP | the keryn_ai_attribution tool: aggregate only, never broken down by developer |
7. Apply an organization AI usage policy
Section titled “7. Apply an organization AI usage policy”Keep the policy in Git so reviewers can see changes and repositories can use the same configuration. Put the policy under .keryn/policy.yml in each repository where the trusted CI job evaluates it.
apiVersion: keryn.dev/policy/v1rules: []aiUsage: - id: production-code repositories: [example/platform, example/api] paths: [src/**, CLAUDE.md] allowTools: [copilot, claude-code] denyTools: [unknown-ai] disclosure: commitTrailer: AI-Disclosure - id: platform-review repositories: [example/platform] disclosure: prLabel: ai-reviewedTo try the policy locally, save the YAML above as demo-policy.yml alongside the demo repository. Use the example/api repository scope to exercise the commit trailer rule. The second demo commit changed CLAUDE.md and declared Claude Code assistance, but it omitted the required AI-Disclosure trailer. The scan exits 1.
keryn attribution scan attribution-demo --repository example/api --policy demo-policy.yml --json policy-result.jsonjq -c '.findings[] | select(.ruleId | startswith("ai-usage.")) | {ruleId, severity, path}' policy-result.json{"ruleId":"ai-usage.production-code.disclosure","severity":"ERROR","path":"CLAUDE.md"}AI usage policy enforcement requires a CLI built from source with this feature or a later signed, entitlement-gated release. The released CLI 0.5.2 does not include attribution. Enable attribution: true in the Keryn GitHub Action to evaluate the base policy in its PR summary and annotations. For JSON or SARIF findings, run keryn attribution scan . --policy .keryn/policy.yml --json result.json in a trusted GitHub pull-request job. The scan reads the policy from the base commit and takes the repository, commit range and labels from the trusted pull-request event. Outside pull-request CI, supply --repository owner/repo. A rule that requires a PR label needs the event to evaluate disclosure.
Path scopes match the file names changed by each commit. Findings cite the commit and evidence channel, and identify the developer by alias. Use keryn attribution rules for tool IDs. A trailer belongs in the commit footer, and unavailable path or label evidence makes coverage incomplete.
Use the policy’s existing expiring waivers for exceptions. Set the waiver’s rule to the finding’s ruleId and its component to the finding’s metadata.subject, and record an independent reviewer’s login as the owner. In pull-request CI, the waiver must already be on the trusted base and the reviewer must differ from the PR author.