claude-attribution 1.2.8 → 1.3.0

package/README.md

@@ -11,7 +11,7 @@
 > ```
 > From then on, just work normally. After each `git commit` you'll see a one-line attribution summary in your terminal. When you're ready to open a PR, run `/pr` in Claude Code (or `claude-attribution pr "feat: your title"`) — it fills in the metrics automatically, no copy-paste needed.
 >
-> **Using Copilot?** The tool still works for tracking Claude usage alongside Copilot. Copilot line-level attribution isn't supported yet — for Copilot-specific stats, use the GitHub Copilot usage dashboard. Both tools' org-level data flows into the VP Datadog dashboard automatically on every PR merge.
+> **Using Copilot or @claude (claude-code-action)?** Commits made by AI bots (Copilot coding agent, `@claude` via claude-code-action) are automatically detected and attributed as 100% AI in metrics — no extra steps needed. See [AI Actor Attribution](#ai-actor-attribution-copilot-bot-claude-gha) for details. For Copilot-specific org-level stats, use the GitHub Copilot usage dashboard. Both tools' data flows into the VP Datadog dashboard automatically on every PR merge.
 >
 > **Requirements:** [Bun](https://bun.sh) (preferred) or Node 18+, and `gh` (GitHub CLI) authenticated for the `/pr` command.
 
@@ -21,6 +21,42 @@ AI code attribution tracking for Claude Code. Measures which lines in a commit w
 
 ---
 
+## GitHub Actions Requirements
+
+Three workflows are installed into repos that use this tool. Each requires specific GitHub Actions to be allowed in your org. If your org enforces an action allowlist, you must approve the third-party action before the workflows will run.
+
+### Workflows and the actions they use
+
+| Workflow file | Trigger | GitHub-owned actions | Third-party actions |
+|---|---|---|---|
+| `claude-attribution-pr.yml` | PR opened / pushed | `actions/checkout@v4`, `actions/github-script@v7` | `oven-sh/setup-bun@v2` |
+| `claude-attribution.yml` | PR merged | `actions/checkout@v4` | `oven-sh/setup-bun@v2` |
+| `claude-attribution-gha.yml` | Every push (optional) | `actions/checkout@v4` | `oven-sh/setup-bun@v2` |
+
+**GitHub-owned actions** (`actions/*`) are pre-approved in all orgs by default.
+
+**`oven-sh/setup-bun@v2`** is a third-party action from the [Bun](https://bun.sh) team. It installs the Bun runtime so the `claude-attribution` CLI can execute without falling back to `npx tsx`. If your org requires explicit action approvals, add `oven-sh/setup-bun` to the allowlist at:
+
+> Settings → Actions → General → Allow actions and reusable workflows → add `oven-sh/setup-bun@*`
+
+### Workflow permissions
+
+| Workflow | `contents` | `pull-requests` | Why |
+|---|---|---|---|
+| `claude-attribution-pr.yml` | read | write | Reads git history; writes metrics into the PR body |
+| `claude-attribution.yml` | read | — | Reads git notes and pushes Datadog metrics |
+| `claude-attribution-gha.yml` | write | — | Pushes attribution git notes back to origin |
+
+### Required secrets
+
+| Secret / Variable | Workflow | Required | Notes |
+|---|---|---|---|
+| `GITHUB_TOKEN` | All | Automatic | Provided by GitHub Actions; no setup needed |
+| `DATADOG_API_KEY` | `claude-attribution.yml` | Yes | Org-level secret; needed to push metrics to Datadog |
+| `DATADOG_SITE` | `claude-attribution.yml` | No | Org-level variable; defaults to `datadoghq.com` |
+
+---
+
 ## For Repo Maintainers: Installing Into a Repo
 
 ### Prerequisites
@@ -103,6 +139,8 @@ The installer makes the following changes to the target repo:
 
 **`.github/workflows/claude-attribution-pr.yml`** — GitHub Actions workflow that fires on every PR open and push. Injects metrics into the PR body automatically for PRs created outside Claude (Copilot, manual `gh pr create`, GitHub UI). Skips injection if the local `post-bash` hook already injected metrics on `opened`; always updates on `synchronize` (new commits).
 
+**`.github/workflows/claude-attribution-gha.yml`** *(optional — installed when claude-code-action is detected)* — fires on every push. Writes a 100% AI git note for commits made by known AI actors (e.g. `@claude` via claude-code-action, Copilot coding agent). Silent no-op for human commits. See [AI Actor Attribution](#ai-actor-attribution-copilot-bot-claude-gha).
+
 **`.claude/commands/`** — installs two slash commands:
 - `/metrics` — generate a PR metrics report
 - `/start` — mark the start of a new Jira ticket session
@@ -461,6 +499,85 @@ All metrics are tagged `repo:`, `pr:`, `branch:`, `author:`, `tool:` — enablin
 
 ---
 
+## AI Actor Attribution (Copilot Bot, @claude GHA)
+
+The local post-commit hook only runs when code is committed on a developer's machine. Commits made server-side by AI bots — such as `@claude` via [claude-code-action](https://github.com/anthropics/claude-code-action) or the Copilot coding agent — bypass the local hook entirely and would otherwise appear as 100% human in metrics.
+
+claude-attribution handles these two ways:
+
+### 1. Auto-detection in metrics (no setup required)
+
+When generating PR metrics, branch commits that have no git note are checked for known AI actor signals:
+
+| Signal | Example |
+|---|---|
+| Bot author email/name | `github-actions[bot]`, `copilot[bot]` |
+| `Co-authored-by:` trailer | `Co-authored-by: Claude <...>` |
+| `Co-authored-by:` trailer | `Co-authored-by: GitHub Copilot <...>` |
+
+If detected, all non-blank committed lines are counted as AI in the metrics output. No git note is written — this is a metrics-time synthesis only.
+
+**Not detectable:** Copilot "Commit suggestion" (the button on PR review comments). Those commits are authored as the human who clicked the button — there is no metadata distinguishing them from a human edit. They will count as HUMAN.
+
+### 2. `note-ai-commit` command (writes a permanent git note)
+
+For `@claude` via claude-code-action, you can write a permanent git note at CI time so attribution is durable (survives metrics regeneration, appears in Datadog dashboard):
+
+```bash
+# Write a 100% AI note for HEAD (then push the note):
+claude-attribution note-ai-commit --push
+
+# Only write the note if the commit looks like an AI actor commit (safe on every push):
+claude-attribution note-ai-commit --if-ai-actor --push
+
+# Write a note for a specific SHA:
+claude-attribution note-ai-commit abc1234 --push
+```
+
+#### Setting up for claude-code-action
+
+If your repo uses [anthropics/claude-code-action](https://github.com/anthropics/claude-code-action), run `claude-attribution install` — it detects the action and offers to install `claude-attribution-gha.yml`, which records attribution automatically on every AI actor push.
+
+To install the workflow manually, add `.github/workflows/claude-attribution-gha.yml`:
+
+```yaml
+name: Claude Attribution — AI Actor Commits
+
+on:
+  push:
+    branches: ["**"]
+
+permissions:
+  contents: write
+
+jobs:
+  note-ai-commit:
+    name: Record AI actor commit attribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Fetch attribution notes
+        run: git fetch origin refs/notes/claude-attribution:refs/notes/claude-attribution || true
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install claude-attribution
+        run: |
+          npm install -g --prefix "${HOME}/.npm-global" claude-attribution
+          echo "${HOME}/.npm-global/bin" >> "$GITHUB_PATH"
+
+      - name: Record attribution if AI actor commit
+        run: claude-attribution note-ai-commit --if-ai-actor --push
+```
+
+The `--if-ai-actor` flag makes this a silent no-op for human commits — it only fires when the commit author or message matches a known AI actor pattern.
+
+---
+
 ## OTel Traces (optional)
 
 claude-attribution can export OpenTelemetry traces to any OTLP-compatible backend (Datadog APM, Jaeger, Tempo, etc.). This is **opt-in** — set one env var to enable it.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-attribution",
-	"version": "1.2.8",
+	"version": "1.3.0",
 	"description": "AI code attribution tracking for Claude Code sessions — checkpoint-based line diff approach",
 	"type": "module",
 	"bin": {

package/src/attribution/git-notes.ts

@@ -13,7 +13,11 @@
  */
 import { execFile } from "child_process";
 import { promisify } from "util";
-import type { AttributionResult } from "./differ.ts";
+import {
+	aggregateTotals,
+	type AttributionResult,
+	type FileAttribution,
+} from "./differ.ts";
 
 const execFileAsync = promisify(execFile);
 const NOTES_REF = "refs/notes/claude-attribution";
@@ -183,3 +187,129 @@ export async function committedContent(
 		return null;
 	}
 }
+
+/**
+ * Read the committed content of a file at any commit SHA.
+ * Returns null for deleted files or binary files should not be processed.
+ */
+export async function committedContentAt(
+	repoRoot: string,
+	sha: string,
+	relPath: string,
+): Promise<string | null> {
+	try {
+		return await runRaw("git", ["show", `${sha}:${relPath}`], repoRoot);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * List relative paths of files changed in any commit (not just HEAD).
+ */
+export async function filesInCommitAt(
+	repoRoot: string,
+	sha: string,
+): Promise<string[]> {
+	const output = await run(
+		"git",
+		["diff-tree", "--no-commit-id", "-r", "--name-only", sha],
+		repoRoot,
+	);
+	return output ? output.split("\n").filter(Boolean) : [];
+}
+
+export interface CommitMeta {
+	authorName: string;
+	authorEmail: string;
+	/** Full commit message body. */
+	message: string;
+	/** Committer date in ISO 8601 format. */
+	timestamp: string;
+}
+
+/**
+ * Get author, email, message, and timestamp for any commit SHA.
+ */
+export async function getCommitMeta(
+	repoRoot: string,
+	sha: string,
+): Promise<CommitMeta> {
+	const nameEmail = await run(
+		"git",
+		["log", "-1", "--format=%an\n%ae", sha],
+		repoRoot,
+	);
+	const [authorName = "", authorEmail = ""] = nameEmail.split("\n");
+	const message = await run("git", ["log", "-1", "--format=%B", sha], repoRoot);
+	const timestamp = await run(
+		"git",
+		["log", "-1", "--format=%cI", sha],
+		repoRoot,
+	);
+	return { authorName, authorEmail, message, timestamp };
+}
+
+/**
+ * Return true if the commit was made by a known AI actor:
+ *   - Bot authors: github-actions[bot], copilot[bot], etc.
+ *   - Co-authored-by trailers referencing Claude or Copilot.
+ *
+ * Used to synthesize 100% AI attribution for commits that bypass the local
+ * post-commit hook (e.g. @claude via claude-code-action, Copilot coding agent).
+ */
+export function isKnownAiActorCommit(meta: CommitMeta): boolean {
+	const { authorName, authorEmail, message } = meta;
+	if (authorEmail.includes("[bot]") || authorName.includes("[bot]"))
+		return true;
+	if (/co-authored-by:.*claude/i.test(message)) return true;
+	if (/co-authored-by:.*copilot/i.test(message)) return true;
+	return false;
+}
+
+/**
+ * Build a 100% AI AttributionResult for a commit without running the
+ * checkpoint-based differ. All non-blank committed lines are marked AI.
+ *
+ * Used by `note-ai-commit` (to write git notes in GHA) and by `collect.ts`
+ * (to synthesize attribution at metrics time for unattributed AI actor commits).
+ */
+export async function buildAllAiResult(
+	repoRoot: string,
+	sha: string,
+): Promise<AttributionResult> {
+	const [changedFiles, meta] = await Promise.all([
+		filesInCommitAt(repoRoot, sha),
+		getCommitMeta(repoRoot, sha),
+	]);
+
+	const fileResults: FileAttribution[] = (
+		await Promise.all(
+			changedFiles.map(async (relPath): Promise<FileAttribution | null> => {
+				const content = await committedContentAt(repoRoot, sha, relPath);
+				if (content === null || content.includes("\0")) return null;
+				const lines = content.split("\n");
+				const ai = lines.filter((l) => l.trim().length > 0).length;
+				const human = lines.length - ai;
+				const total = lines.length;
+				return {
+					path: relPath,
+					ai,
+					human,
+					mixed: 0,
+					total,
+					pctAi: total > 0 ? Math.round((ai / total) * 100) : 0,
+				};
+			}),
+		)
+	).filter((f): f is FileAttribution => f !== null);
+
+	return {
+		commit: sha,
+		session: null,
+		branch: null,
+		timestamp: meta.timestamp,
+		files: fileResults,
+		totals: aggregateTotals(fileResults),
+	};
+}

package/src/cli.ts

@@ -30,6 +30,9 @@ switch (cmd) {
 	case "pr":
 		await import("./commands/pr.ts");
 		break;
+	case "note-ai-commit":
+		await import("./commands/note-ai-commit.ts");
+		break;
 	case "init":
 		await import("./commands/init.ts");
 		break;
@@ -93,6 +96,7 @@ Commands:
   metrics [id]     Generate PR metrics report
   pr [title]       Create PR with metrics embedded (--draft, --base <branch>)
   init [--ai | --ai-since <YYYY-MM-DD>]  Set attribution baseline in the cumulative minimap
+  note-ai-commit [sha] [--push] [--if-ai-actor]  Write 100% AI git note for a commit (GHA use)
   start            Mark session start for per-ticket scoping
   hook <name>      Run an internal hook (used by installed git hooks)
   version          Print version

package/src/commands/note-ai-commit.ts

@@ -0,0 +1,69 @@
+/**
+ * note-ai-commit — write a 100% AI attribution git note for a commit.
+ *
+ * Usage: claude-attribution note-ai-commit [sha] [--push] [--if-ai-actor]
+ *
+ * Used as a step in claude-code-action GHA workflows to record that all
+ * lines committed by @claude are AI-authored. Defaults to HEAD.
+ *
+ * Options:
+ *   --push          Push the note to origin after writing.
+ *   --if-ai-actor   Only write the note if the commit looks like it was made
+ *                   by a known AI actor (bot author or Co-authored-by trailer).
+ *                   Silent no-op otherwise — safe to run on every push.
+ *
+ * All non-blank lines in the committed files are attributed as AI. Blank
+ * lines are always HUMAN per the attribution algorithm in differ.ts.
+ */
+import { resolve } from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import {
+	writeNote,
+	headSha,
+	getCommitMeta,
+	isKnownAiActorCommit,
+	buildAllAiResult,
+} from "../attribution/git-notes.ts";
+
+const execFileAsync = promisify(execFile);
+const NOTES_REF = "refs/notes/claude-attribution";
+
+async function main() {
+	const args = process.argv.slice(2);
+	const pushFlag = args.includes("--push");
+	const ifAiActorFlag = args.includes("--if-ai-actor");
+	const sha = args.find((a) => !a.startsWith("--")) ?? null;
+
+	const repoRoot = resolve(process.cwd());
+	const commitSha = sha ?? (await headSha(repoRoot));
+
+	if (ifAiActorFlag) {
+		const meta = await getCommitMeta(repoRoot, commitSha);
+		if (!isKnownAiActorCommit(meta)) return; // silent no-op
+	}
+
+	const result = await buildAllAiResult(repoRoot, commitSha);
+	await writeNote(result, repoRoot, commitSha);
+
+	const { totals } = result;
+	console.log(
+		`[claude-attribution] ${commitSha.slice(0, 7)} — ${totals.ai} AI / ${totals.human} human / 0 mixed lines (${totals.pctAi}% AI) [ai-actor]`,
+	);
+
+	if (pushFlag) {
+		await execFileAsync(
+			"git",
+			["push", "origin", `${NOTES_REF}:${NOTES_REF}`],
+			{
+				cwd: repoRoot,
+			},
+		);
+		console.log("[claude-attribution] pushed attribution note");
+	}
+}
+
+main().catch((err) => {
+	console.error("[claude-attribution] note-ai-commit error:", err);
+	process.exit(1);
+});

package/src/metrics/collect.ts

@@ -15,6 +15,9 @@ import {
 	listNotes,
 	readNote,
 	getBranchCommitShas,
+	getCommitMeta,
+	isKnownAiActorCommit,
+	buildAllAiResult,
 } from "../attribution/git-notes.ts";
 import {
 	aggregateTotals,
@@ -173,6 +176,7 @@ async function getBranchAttribution(
 		listNotes(repoRoot),
 		getBranchCommitShas(repoRoot),
 	]);
+	const notedSet = new Set(allShas);
 	const branchSet = new Set(branchShas);
 	const shasToRead =
 		branchShas.length > 0
@@ -189,6 +193,30 @@ async function getBranchAttribution(
 		notes.push(...batchResults);
 	}
 	const results = notes.filter((n): n is AttributionResult => n !== null);
+
+	// Synthesize attribution for branch commits with no note that look like
+	// AI actor commits (e.g. @claude via claude-code-action, Copilot coding agent).
+	// These bypass the local post-commit hook, so no note is ever written for them.
+	const unnotedBranchShas = branchShas.filter((sha) => !notedSet.has(sha));
+	if (unnotedBranchShas.length > 0) {
+		const synthetic = (
+			await Promise.all(
+				unnotedBranchShas.map(
+					async (sha): Promise<AttributionResult | null> => {
+						try {
+							const meta = await getCommitMeta(repoRoot, sha);
+							if (!isKnownAiActorCommit(meta)) return null;
+							return buildAllAiResult(repoRoot, sha);
+						} catch {
+							return null;
+						}
+					},
+				),
+			)
+		).filter((r): r is AttributionResult => r !== null);
+		results.push(...synthetic);
+	}
+
 	if (sessionStart) {
 		return results.filter((r) => new Date(r.timestamp) >= sessionStart);
 	}

package/src/setup/branch-protection.ts

@@ -333,20 +333,16 @@ export async function configureRequiredCheck(repoRoot: string): Promise<void> {
 			getRulesetStatuses(slug),
 		]);
 
-		// Determine what needs to be added
-		const classicNeeded = classic !== null && !classic.hasOurCheck;
-		const rulesetsNeeded = rulesets.filter((rs) => !rs.hasOurCheck);
-
-		// Already fully configured
-		if (!classicNeeded && rulesetsNeeded.length === 0) {
-			if (classic?.hasOurCheck || rulesets.some((rs) => rs.hasOurCheck)) {
-				console.log(
-					`✓ '${WORKFLOW_CHECK_NAME}' already a required status check`,
-				);
-			}
+		// Already configured on at least one target — don't prompt again
+		if (classic?.hasOurCheck || rulesets.some((rs) => rs.hasOurCheck)) {
+			console.log(`✓ '${WORKFLOW_CHECK_NAME}' already a required status check`);
 			return;
 		}
 
+		// Determine what needs to be added
+		const classicNeeded = classic !== null;
+		const rulesetsNeeded = rulesets;
+
 		// Build the list of targets that need our check
 		const targets: Array<
 			| { kind: "classic"; classic: ClassicStatus }

package/src/setup/install.ts

@@ -5,7 +5,7 @@
  *
  * If no path is given, installs into the current working directory.
  */
-import { readFile, writeFile, appendFile, mkdir } from "fs/promises";
+import { readFile, writeFile, appendFile, mkdir, readdir } from "fs/promises";
 import { existsSync } from "fs";
 import { execFile } from "child_process";
 import { promisify } from "util";
@@ -140,6 +140,79 @@ async function promptBaselineInit(
 	}
 }
 
+/** Return true if any workflow in the repo references claude-code-action. */
+async function detectClaudeCodeAction(repoRoot: string): Promise<boolean> {
+	const workflowsDir = join(repoRoot, ".github", "workflows");
+	if (!existsSync(workflowsDir)) return false;
+	try {
+		const files = await readdir(workflowsDir);
+		for (const file of files) {
+			if (!file.endsWith(".yml") && !file.endsWith(".yaml")) continue;
+			if (file.startsWith("claude-attribution")) continue;
+			const content = await readFile(join(workflowsDir, file), "utf8");
+			if (content.includes("anthropics/claude-code-action")) return true;
+		}
+	} catch {
+		// ignore
+	}
+	return false;
+}
+
+/**
+ * Install the AI actor attribution workflow when claude-code-action is present.
+ * Always overwrites if already installed (idempotent upgrade). Prompts on first install.
+ */
+async function installGhaWorkflow(repoRoot: string): Promise<void> {
+	const destPath = join(
+		repoRoot,
+		".github",
+		"workflows",
+		"claude-attribution-gha.yml",
+	);
+	const templatePath = join(
+		ATTRIBUTION_ROOT,
+		"src",
+		"setup",
+		"templates",
+		"claude-attribution-gha.yml",
+	);
+	const template = await readFile(templatePath, "utf8");
+
+	// Always update if already installed
+	if (existsSync(destPath)) {
+		await writeFile(destPath, template);
+		console.log("✓ Updated .github/workflows/claude-attribution-gha.yml");
+		return;
+	}
+
+	// First install — only if claude-code-action is detected
+	const hasClaudeAction = await detectClaudeCodeAction(repoRoot);
+	if (!hasClaudeAction) return;
+
+	if (!process.stdin.isTTY) {
+		console.log(
+			"  ℹ️  claude-code-action detected — run install interactively to add AI actor attribution workflow.",
+		);
+		return;
+	}
+
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	const yes = await new Promise<boolean>((resolve) => {
+		rl.question(
+			"\n  claude-code-action detected. Install AI actor attribution workflow? [y/N] ",
+			(answer) => {
+				rl.close();
+				resolve(answer.trim().toLowerCase() === "y");
+			},
+		);
+	});
+
+	if (yes) {
+		await writeFile(destPath, template);
+		console.log("✓ Installed .github/workflows/claude-attribution-gha.yml");
+	}
+}
+
 async function main() {
 	const args = process.argv.slice(2);
 	const runnerFlagIdx = args.findIndex((a: string) => a === "--runner");
@@ -290,6 +363,9 @@ async function main() {
 		`✓ Installed .github/workflows/claude-attribution-pr.yml — runner: ${runsOn}${detectedNote}`,
 	);
 
+	// 4b. Install GHA attribution workflow if claude-code-action is present
+	await installGhaWorkflow(targetRepo);
+
 	// 5. Check branch protection and offer to add required status check
 	await configureRequiredCheck(targetRepo);
 

package/src/setup/templates/claude-attribution-gha.yml

@@ -0,0 +1,38 @@
+name: Claude Attribution — AI Actor Commits
+
+# Records attribution for commits made by AI actors that bypass the local
+# post-commit hook (e.g. @claude via claude-code-action, Copilot coding agent).
+#
+# Uses --if-ai-actor so this is a no-op for regular human pushes — it only
+# writes and pushes a git note when the commit author or Co-authored-by trailer
+# identifies the commit as AI-authored.
+
+on:
+  push:
+    branches: ["**"]
+
+permissions:
+  contents: write
+
+jobs:
+  note-ai-commit:
+    name: Record AI actor commit attribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Fetch attribution notes
+        run: git fetch origin refs/notes/claude-attribution:refs/notes/claude-attribution || true
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install claude-attribution
+        run: |
+          npm install -g --prefix "${HOME}/.npm-global" claude-attribution
+          echo "${HOME}/.npm-global/bin" >> "$GITHUB_PATH"
+
+      - name: Record attribution if AI actor commit
+        run: claude-attribution note-ai-commit --if-ai-actor --push

package/src/setup/templates/pr-metrics-workflow.yml

@@ -22,10 +22,11 @@ jobs:
           git fetch origin refs/notes/claude-attribution:refs/notes/claude-attribution || true
           git fetch origin refs/notes/claude-attribution-map:refs/notes/claude-attribution-map || true
 
+      - uses: oven-sh/setup-bun@v2
+
       - name: Install claude-attribution
         run: |
-          npm config set prefix "${HOME}/.npm-global"
-          npm install -g claude-attribution
+          npm install -g --prefix "${HOME}/.npm-global" claude-attribution
           echo "${HOME}/.npm-global/bin" >> "$GITHUB_PATH"
 
       - name: Generate metrics