claude-attribution 1.2.0 → 1.2.2

package/README.md

@@ -6,18 +6,14 @@
 > ```bash
 > npm install -g claude-attribution
 > claude-attribution install ~/Code/your-repo
-> git add .claude/settings.json .github/workflows/claude-attribution-pr.yml .gitignore && git commit -m "chore: install claude-attribution hooks"
+> claude-attribution init --ai    # repo built with Claude Code — or --human if human/mixed
+> git add .claude/settings.json .gitignore && git commit -m "chore: install claude-attribution hooks"
 > ```
-> From then on, just work normally. After each `git commit` you'll see a one-line attribution summary in your terminal. When you open a PR — whether Claude creates it or you run `gh pr create` yourself — metrics are injected into the PR body automatically, no command needed.
+> 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.
 >
-> **Already using Claude Code before installing this?** Run `claude-attribution init` once to declare the baseline — this enables the codebase-wide AI% signal in PR metrics:
-> - **All Claude Code:** `claude-attribution init --ai && git push origin refs/notes/claude-attribution-map`
-> - **All human (or mixed):** `claude-attribution init` (or `--human`) — prints a confirmation, no note written; human is the default
-> - **Not sure?** Default to `--human`. Attribution accumulates accurately from new commits forward.
+> **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?** 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 under your organization's Settings → Copilot. Both tools' org-level 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.
+> **Requirements:** [Bun](https://bun.sh) (preferred) or Node 18+, and `gh` (GitHub CLI) authenticated for the `/pr` command.
 
 ---
 
@@ -51,17 +47,45 @@ bun install
 
 ### Install into a repo (per repo, per developer)
 
-**npm install:**
+**Step 1 — Run the installer:**
+
 ```bash
+# npm install:
 claude-attribution install ~/Code/your-repo
+
+# clone install:
+bun ~/Code/claude-attribution/src/setup/install.ts ~/Code/your-repo
 ```
 
-**Clone install:**
+**Step 2 — Declare your attribution baseline (`init`):**
+
+This step tells the tool whether the codebase was written by Claude or by humans before this install. It only needs to be run once.
+
 ```bash
-bun ~/Code/claude-attribution/src/setup/install.ts ~/Code/your-repo
+# Repo was built entirely with Claude Code — mark all files as AI-written:
+claude-attribution init --ai
+
+# Repo is human-written, or a mix — confirm the default (no note written):
+claude-attribution init --human
+
+# Not sure? Run with no flag — same as --human, prints a confirmation:
+claude-attribution init
+```
+
+> **Why this matters:** Without `init`, the codebase-wide AI% starts at 0% and grows only from new commits. If your repo is all Claude Code, run `init --ai` now or the metrics will be misleading until the entire codebase has been re-committed line by line.
+
+**Step 3 — Commit and push:**
+
+```bash
+git add .claude/settings.json .github/workflows/claude-attribution-pr.yml .gitignore
+git commit -m "chore: install claude-attribution hooks"
+git push
+
+# If you ran init --ai, also push the minimap notes:
+git push origin refs/notes/claude-attribution-map
 ```
 
-The installer makes six changes to the target repo:
+The installer makes the following changes to the target repo:
 
 **`.claude/settings.json`** — merges six Claude Code hooks:
 
@@ -85,17 +109,7 @@ The installer makes six changes to the target repo:
 
 **`.gitignore`** — adds `.claude/logs/` so tool usage logs don't end up in version control.
 
-### Committing the settings change
-
-The `.claude/settings.json` and workflow changes should be committed so all developers get the hooks and all PRs get metrics automatically.
-
-```bash
-# After running the installer:
-git add .claude/settings.json .github/workflows/claude-attribution-pr.yml .gitignore
-git commit -m "chore: install claude-attribution hooks"
-```
-
-### Backfilling the attribution minimap
+### Attribution minimap — detailed options
 
 The attribution minimap tracks cumulative AI% across the entire codebase, carrying attribution forward across sessions and developers. For new commits it is updated automatically. For the history that predates the install, you declare the baseline once using `claude-attribution init`.
 

package/package.json

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

package/src/attribution/minimap.ts

@@ -18,6 +18,9 @@
  */
 import { execFile } from "child_process";
 import { promisify } from "util";
+import { writeFile, unlink, mkdtemp, rmdir } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
 import { hashLine } from "./differ.ts";
 
 const execFileAsync = promisify(execFile);
@@ -107,21 +110,38 @@ export async function writeMinimap(
 	repoRoot: string,
 	commitSha = "HEAD",
 ): Promise<void> {
-	const json = JSON.stringify(result, null, 2);
-	await run(
-		"git",
-		[
-			"notes",
-			"--ref",
-			MINIMAP_NOTES_REF,
-			"add",
-			"--force",
-			"-m",
-			json,
-			commitSha,
-		],
-		repoRoot,
-	);
+	// Write JSON to a temp file and use -F to avoid E2BIG on large repos.
+	// Passing the full minimap as a -m argument fails when the JSON exceeds
+	// the OS argument size limit (~500KB on macOS).
+	//
+	// Use mkdtemp to create a unique, isolated temp directory rather than a
+	// predictable filename in the shared OS temp dir — prevents collisions
+	// under concurrent runs and symlink/race attacks.
+	const tmpDir = await mkdtemp(join(tmpdir(), "claude-attribution-minimap-"));
+	const tmpFile = join(tmpDir, "minimap.json");
+	try {
+		await writeFile(tmpFile, JSON.stringify(result, null, 2), {
+			encoding: "utf8",
+			flag: "wx",
+		});
+		await run(
+			"git",
+			[
+				"notes",
+				"--ref",
+				MINIMAP_NOTES_REF,
+				"add",
+				"--force",
+				"-F",
+				tmpFile,
+				commitSha,
+			],
+			repoRoot,
+		);
+	} finally {
+		await unlink(tmpFile).catch(() => {});
+		await rmdir(tmpDir).catch(() => {});
+	}
 }
 
 export async function readMinimap(

package/src/commands/init.ts

@@ -16,7 +16,7 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 import { hashLine } from "../attribution/differ.ts";
 import {
-	computeMinimapFile,
+	hashSetToString,
 	writeMinimap,
 	type MinimapFileState,
 	type MinimapResult,
@@ -97,21 +97,27 @@ async function main() {
 					if (content.includes("\0")) return null;
 
 					const lines = content.split("\n");
+					const total = lines.length;
 
-					// Build currentAiHashes from every non-blank line in the file
-					const currentAiHashes = new Set<string>();
+					// init --ai is an explicit declaration: every line (including blank)
+					// is AI-written. Build ai_hashes from all non-blank lines so the
+					// carry-forward algorithm in future commits works correctly; count
+					// blank lines as AI in the totals.
+					const aiHashes = new Set<string>();
 					for (const line of lines) {
 						if (line.trim() !== "") {
-							currentAiHashes.add(hashLine(line));
+							aiHashes.add(hashLine(line));
 						}
 					}
 
-					return computeMinimapFile(
-						relPath,
-						lines,
-						currentAiHashes,
-						new Set<string>(),
-					);
+					return {
+						path: relPath,
+						ai_hashes: hashSetToString(aiHashes),
+						ai: total,
+						human: 0,
+						total,
+						pctAi: total > 0 ? 100 : 0,
+					} satisfies MinimapFileState;
 				} catch {
 					return null;
 				}

package/src/commands/pr.ts

@@ -88,7 +88,7 @@ async function main() {
 			draft = true;
 		} else if (args[i] === "--base" && i + 1 < args.length) {
 			base = args[++i];
-		} else if (!args[i].startsWith("--")) {
+		} else if (!(args[i] ?? "").startsWith("--")) {
 			title = args[i];
 		}
 	}

package/src/hooks/post-bash.ts

@@ -44,7 +44,7 @@ function extractPrUrl(response: unknown): string | null {
 
 function prNumberFromUrl(url: string): number | null {
 	const match = url.match(/\/pull\/(\d+)$/);
-	return match ? parseInt(match[1], 10) : null;
+	return match?.[1] ? parseInt(match[1], 10) : null;
 }
 
 async function main() {

package/src/hooks/pre-tool-use.ts

@@ -20,7 +20,6 @@ import { readStdin, WRITE_TOOLS, getFilePath } from "../lib/hooks.ts";
 import { maybeAutoUpgrade } from "../lib/auto-upgrade.ts";
 import {
 	otelEndpoint,
-	otelHeaders,
 	readOtelContext,
 	writeOtelContext,
 	makeTraceId,

package/src/metrics/transcript.ts

@@ -120,7 +120,7 @@ function computeActiveMinutes(allTimestamps: number[]): number {
 	let totalMs = 0;
 	const IDLE_THRESHOLD_MS = 900_000; // 15 minutes
 	for (let i = 1; i < sorted.length; i++) {
-		const gap = sorted[i] - sorted[i - 1];
+		const gap = (sorted[i] ?? 0) - (sorted[i - 1] ?? 0);
 		if (gap < IDLE_THRESHOLD_MS) totalMs += gap;
 	}
 	return Math.round(totalMs / 60_000);

package/src/setup/install.ts

@@ -25,7 +25,14 @@ const execFileAsync = promisify(execFile);
 const CLI_BIN = resolve(ATTRIBUTION_ROOT, "bin", "claude-attribution");
 
 async function main() {
-	const targetRepo = resolve(process.argv[2] ?? process.cwd());
+	const args = process.argv.slice(2);
+	const runnerFlagIdx = args.findIndex((a: string) => a === "--runner");
+	const runnerOverride =
+		runnerFlagIdx !== -1 ? args[runnerFlagIdx + 1] : undefined;
+	const positional = args.filter(
+		(a: string, i: number) => a !== "--runner" && i !== runnerFlagIdx + 1,
+	);
+	const targetRepo = resolve(positional[0] ?? process.cwd());
 
 	if (!existsSync(join(targetRepo, ".git"))) {
 		console.error(`Error: ${targetRepo} is not a git repository`);
@@ -147,9 +154,13 @@ async function main() {
 	console.log("✓ Installed .claude/commands/pr.md (/pr command)");
 
 	// 4. Install GitHub Actions workflow for automatic PR metrics injection
-	await installCiWorkflow(targetRepo);
+	const { runsOn, detected } = await installCiWorkflow(
+		targetRepo,
+		runnerOverride,
+	);
+	const detectedNote = detected ? " (detected from existing workflows)" : "";
 	console.log(
-		"✓ Installed .github/workflows/claude-attribution-pr.yml (auto-injects metrics on PR open)",
+		`✓ Installed .github/workflows/claude-attribution-pr.yml — runner: ${runsOn}${detectedNote}`,
 	);
 
 	// 5. Record installed version for auto-upgrade tracking

package/src/setup/shared.ts

@@ -4,7 +4,7 @@
  * No top-level side effects. No console.log — logging is the caller's
  * responsibility.
  */
-import { readFile, writeFile, chmod, mkdir } from "fs/promises";
+import { readFile, writeFile, chmod, mkdir, readdir } from "fs/promises";
 import { existsSync } from "fs";
 import { resolve, join, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -169,13 +169,86 @@ export async function installSlashCommands(repoRoot: string): Promise<void> {
 	}
 }
 
+/** GitHub-hosted runner labels — anything else is self-hosted or custom. */
+const GITHUB_HOSTED_RUNNERS = new Set([
+	"ubuntu-latest",
+	"ubuntu-24.04",
+	"ubuntu-22.04",
+	"ubuntu-20.04",
+	"windows-latest",
+	"windows-2025",
+	"windows-2022",
+	"windows-2019",
+	"macos-latest",
+	"macos-15",
+	"macos-14",
+	"macos-13",
+	"macos-12",
+]);
+
+/**
+ * Scan existing workflows in .github/workflows/ (excluding our own) and return
+ * the most common non-GitHub-hosted `runs-on` value, or null if none found.
+ */
+async function detectRunsOn(repoRoot: string): Promise<string | null> {
+	const workflowsDir = join(repoRoot, ".github", "workflows");
+	if (!existsSync(workflowsDir)) return null;
+
+	let files: string[];
+	try {
+		files = await readdir(workflowsDir);
+	} catch {
+		return null;
+	}
+
+	const freq = new Map<string, number>();
+
+	for (const file of files) {
+		if (file === "claude-attribution-pr.yml") continue;
+		if (!file.endsWith(".yml") && !file.endsWith(".yaml")) continue;
+		try {
+			const content = await readFile(join(workflowsDir, file), "utf8");
+			for (const match of content.matchAll(/^\s+runs-on:\s+(.+)$/gm)) {
+				const raw: string = match[1] ?? "";
+				const value = (raw.split("#")[0] ?? raw).trim();
+				if (!GITHUB_HOSTED_RUNNERS.has(value)) {
+					freq.set(value, (freq.get(value) ?? 0) + 1);
+				}
+			}
+		} catch {
+			continue;
+		}
+	}
+
+	if (freq.size === 0) return null;
+	const sorted = [...freq.entries()].sort((a, b) => b[1] - a[1]);
+	return sorted[0]?.[0] ?? null;
+}
+
 /**
  * Install (or overwrite) the GitHub Actions PR metrics workflow.
+ * Auto-detects the runner from existing workflows; override with runsOn param.
+ * Returns the runner value used and whether it was auto-detected.
  */
-export async function installCiWorkflow(repoRoot: string): Promise<void> {
+export async function installCiWorkflow(
+	repoRoot: string,
+	runsOn?: string,
+): Promise<{ runsOn: string; detected: boolean }> {
 	const workflowsDir = join(repoRoot, ".github", "workflows");
 	await mkdir(workflowsDir, { recursive: true });
-	const content = await readFile(
+
+	let detected = false;
+	if (!runsOn) {
+		const autoDetected = await detectRunsOn(repoRoot);
+		if (autoDetected) {
+			runsOn = autoDetected;
+			detected = true;
+		} else {
+			runsOn = "ubuntu-latest";
+		}
+	}
+
+	const template = await readFile(
 		join(
 			ATTRIBUTION_ROOT,
 			"src",
@@ -185,5 +258,9 @@ export async function installCiWorkflow(repoRoot: string): Promise<void> {
 		),
 		"utf8",
 	);
-	await writeFile(join(workflowsDir, "claude-attribution-pr.yml"), content);
+	await writeFile(
+		join(workflowsDir, "claude-attribution-pr.yml"),
+		template.replace("{{RUNS_ON}}", runsOn),
+	);
+	return { runsOn, detected };
 }

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

@@ -11,7 +11,7 @@ permissions:
 jobs:
   metrics:
     name: Claude Code Attribution Metrics
-    runs-on: ubuntu-latest
+    runs-on: {{RUNS_ON}}
     steps:
       - uses: actions/checkout@v4
         with: