claude-attribution 1.2.9 → 1.5.0

package/README.md

@@ -1,23 +1,70 @@
 # claude-attribution
 
-> **Hey team** — we've built a tool that automatically tracks and documents AI contribution in your PRs so you don't have to do it manually.
->
-> **One-time setup:**
-> ```bash
-> npm install -g claude-attribution
-> claude-attribution install ~/Code/your-repo
-> 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'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.
->
-> **Requirements:** [Bun](https://bun.sh) (preferred) or Node 18+, and `gh` (GitHub CLI) authenticated for the `/pr` command.
+AI code attribution for Claude Code. After every `git commit`, a one-line summary appears in your terminal:
+
+```
+[claude-attribution] a3f1b2c — 142 AI / 38 human / 4 mixed lines (77% AI)
+```
+
+When a PR is opened, full metrics — model usage, token counts, tool calls, and attribution percentages — are injected automatically into the PR body. No copy-paste, no manual tracking.
+
+**Quick start:**
+
+```bash
+npm install -g claude-attribution
+claude-attribution install ~/Code/your-repo
+claude-attribution init --ai    # if repo was built with Claude Code; use --human otherwise
+git add .claude/settings.json .github/workflows/claude-attribution-pr.yml .gitignore
+git commit -m "chore: install claude-attribution hooks"
+git push
+```
+
+**Using Copilot or `@claude` (claude-code-action)?** Bot commits are auto-detected and attributed as 100% AI — no extra steps needed. See [AI Actor Attribution](#ai-actor-attribution-copilot-bot-claude-gha).
+
+**Requirements:** [Bun](https://bun.sh) (preferred) or Node 18+, and `gh` (GitHub CLI) authenticated for the `/pr` command.
+
+---
+
+Measures which lines in a commit were written by Claude vs. a human — using checkpoint snapshots and line-level SHA-256 comparison, not gross write-operation counts.
 
 ---
 
-AI code attribution tracking for Claude Code. Measures which lines in a commit were written by Claude vs. a human — using checkpoint snapshots and line-level SHA-256 comparison, not gross write-operation counts.
+## GitHub Actions Requirements
+
+Up to three workflows are installed into repos that use this tool — one always, two optionally. 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 | Install | GitHub-owned actions | Third-party actions |
+|---|---|---|---|---|
+| `claude-attribution-pr.yml` | PR opened / pushed | Always | `actions/checkout@v4`, `actions/github-script@v7` | `oven-sh/setup-bun@v2` |
+| `claude-attribution-export.yml` | PR merged | Optional (prompted) | `actions/checkout@v4` | `oven-sh/setup-bun@v2` |
+| `claude-attribution-gha.yml` | Every push | Optional (claude-code-action detected) | `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-export.yml` | read | — | Reads git notes and exports metrics via OTLP/webhook |
+| `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 |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `claude-attribution-export.yml` | One of these | OTLP/HTTP base URL (e.g. `https://otlp.datadoghq.com`, `https://otlp-gateway-<zone>.grafana.net/otlp`, `http://localhost:4318`). Unset = dry-run mode. |
+| `OTEL_EXPORTER_OTLP_HEADERS` | `claude-attribution-export.yml` | Depends on backend | Comma-separated `key=value` auth headers (e.g. `DD-Api-Key=xxx` for Datadog, `x-honeycomb-team=xxx` for Honeycomb) |
+| `DATADOG_API_KEY` | `claude-attribution-export.yml` | Datadog shortcut | Org-level secret; auto-configures the Datadog OTLP endpoint without needing `OTEL_EXPORTER_OTLP_ENDPOINT`. |
+| `DATADOG_SITE` | `claude-attribution-export.yml` | No | Org-level variable; used with `DATADOG_API_KEY`. Defaults to `datadoghq.com`. |
+| `METRICS_WEBHOOK_URL` | `claude-attribution-export.yml` | No | Posts a flat JSON payload to any HTTP endpoint on each PR merge. Can be used alongside OTLP. |
 
 ---
 
@@ -31,30 +78,16 @@ AI code attribution tracking for Claude Code. Measures which lines in a commit w
 
 ### One-time setup (per developer machine)
 
-**Option A — npm (recommended):**
-
 ```bash
 npm install -g claude-attribution
 ```
 
-**Option B — clone (if npm isn't available):**
-
-```bash
-git clone git@github.com:DTS-Productivity-Engineering/claude-attribution.git ~/Code/claude-attribution
-cd ~/Code/claude-attribution
-bun install
-```
-
 ### Install into a repo (per repo, per developer)
 
 **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
 ```
 
 **Step 2 — Declare your attribution baseline (`init`):**
@@ -70,6 +103,9 @@ claude-attribution init --human
 
 # Not sure? Run with no flag — same as --human, prints a confirmation:
 claude-attribution init
+
+# Repo has mixed history — mark commits after a specific date as AI-written:
+claude-attribution init --ai-since 2025-01-01
 ```
 
 > **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.
@@ -103,9 +139,14 @@ 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).
 
-**`.claude/commands/`** — installs two slash commands:
+**`.github/workflows/claude-attribution-export.yml`** — fires on every PR merge. Exports AI attribution metrics via OTLP/HTTP or a generic webhook. Supports Datadog, Grafana Cloud, Splunk Observability, New Relic, Honeycomb, and any OpenTelemetry Collector. Runs in dry-run mode (prints payload to stdout, exits 0) when no export destination is configured. See [Metrics Export](#metrics-export).
+
+**`.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 three slash commands:
 - `/metrics` — generate a PR metrics report
-- `/start` — mark the start of a new Jira ticket session
+- `/start` — mark the start of a new ticket session
+- `/pr` — create a PR with metrics embedded
 
 **`.gitignore`** — adds `.claude/logs/` so tool usage logs don't end up in version control.
 
@@ -139,16 +180,12 @@ claude-attribution init --ai     # only if repo was built 100% with Claude Code
 git push origin refs/notes/claude-attribution-map
 ```
 
-### Re-installing after moving this directory
+### Re-installing
 
-If you move `~/Code/claude-attribution` to a different path, re-run the installer — it updates the absolute paths in `settings.json` and the git hook:
+If you reinstall `claude-attribution` globally (e.g. after upgrading), re-run the installer — it updates the absolute paths in `settings.json` and the git hook:
 
 ```bash
-# npm install:
 claude-attribution install ~/Code/your-repo
-
-# clone install:
-bun src/setup/install.ts ~/Code/your-repo
 ```
 
 ### Uninstalling
@@ -156,14 +193,10 @@ bun src/setup/install.ts ~/Code/your-repo
 To remove claude-attribution from a repo:
 
 ```bash
-# npm install:
 claude-attribution uninstall ~/Code/your-repo
-
-# clone install:
-bun ~/Code/claude-attribution/src/setup/uninstall.ts ~/Code/your-repo
 ```
 
-This removes hooks from `.claude/settings.json`, removes `.git/hooks/post-commit`, removes the slash commands, removes `.github/workflows/claude-attribution-pr.yml`, and removes any legacy `pre-push` hooks (for example `.husky/pre-push` or `.git/hooks/pre-push`) if present. Attribution state (`.claude/attribution-state/`) and logs (`.claude/logs/`) are left in place. The `remote.origin.push` refspec is also removed from git config.
+This removes hooks from `.claude/settings.json`, removes `.git/hooks/post-commit`, removes the slash commands, removes `.github/workflows/claude-attribution-pr.yml`, `.github/workflows/claude-attribution-export.yml`, and `.github/workflows/claude-attribution-gha.yml` (if present), and removes any legacy `pre-push` hooks (for example `.husky/pre-push` or `.git/hooks/pre-push`) if present. Attribution state (`.claude/attribution-state/`) and logs (`.claude/logs/`) are left in place. The `remote.origin.push` refspec is also removed from git config.
 
 ---
 
@@ -199,33 +232,36 @@ Metrics are injected automatically — no command needed.
 
 **On every new push to an open PR**: the workflow fires on `synchronize` and updates the attribution percentages to reflect new commits.
 
-The metrics block looks like (when the cumulative minimap exists):
-
-```markdown
-## Claude Code Metrics
+The metrics block injected into the PR body looks like (when the cumulative minimap exists):
 
-**Codebase: ~77% AI** (3200 / 4150 lines)
-**This PR:** 184 lines changed (4% of codebase) · 77% Claude edits · 142 AI lines · Active: 8m
+> ## Claude Code Metrics
+>
+> **Codebase: ~77% AI** (3200 / 4150 lines)
+> **This PR:** 184 lines changed (4% of codebase) · 77% Claude edits · 142 AI lines · Active: 8m
+>
+> | Model | Calls | Input | Output | Cache |
+> |-------|-------|-------|--------|-------|
+> | Sonnet | 45 | 120K | 35K | 10K |
+> | **Total** | 45 | 120K | 35K | 10K |
+>
+> **Human prompts (steering effort):** 12
+>
+> <details><summary>Tools · Agents · Files</summary>
+>
+> **Tools:** Edit ×47, Read ×31, Bash ×12
+>
+> </details>
 
-| Model | Calls | Input | Output | Cache |
-|-------|-------|-------|--------|-------|
-| Sonnet | 45 | 120K | 35K | 10K |
-| **Total** | 45 | 120K | 35K | 10K |
+Before running `init --ai` (or on a fresh install with no minimap), the headline falls back to the session-only view:
 
-**Human prompts (steering effort):** 12
+> **AI contribution: ~77%** (142 of 184 committed lines) · Active: 8m
 
-<details>
-<summary>Tools · Agents · Files</summary>
+The block is wrapped in HTML comments for idempotent updates — re-running replaces the existing block rather than appending:
 
-**Tools:** Edit ×47, Read ×31, Bash ×12
-...
-</details>
 ```
-
-Before running `init --ai` (or on a fresh install with no minimap), the headline falls back to the session-only view:
-
-```markdown
-**AI contribution: ~77%** (142 of 184 committed lines) · Active: 8m
+<!-- claude-attribution metrics -->
+...metrics content...
+<!-- /claude-attribution metrics -->
 ```
 
 #### Manual option
@@ -233,7 +269,7 @@ Before running `init --ai` (or on a fresh install with no minimap), the headline
 If you need to create a PR with metrics outside of Claude, use the `/pr` slash command or CLI directly:
 
 ```bash
-claude-attribution pr "feat: COMM-1234 add user authentication"
+claude-attribution pr "feat: PROJ-1234 add user authentication"
 claude-attribution pr "feat: my feature" --draft
 claude-attribution pr "feat: my feature" --base develop
 ```
@@ -246,7 +282,6 @@ To see the metrics output without creating a PR, use `/metrics` or run directly:
 
 ```bash
 claude-attribution metrics
-# or: bun ~/Code/claude-attribution/src/metrics/calculate.ts
 ```
 
 The output is markdown you paste into your PR description:
@@ -313,7 +348,7 @@ Example output:
 {
   "commit": "a3f1b2c",
   "session": "abc-123-...",
-  "branch": "feature/COMM-1234",
+  "branch": "feature/PROJ-1234",
   "timestamp": "2026-03-26T15:32:00.000Z",
   "files": [
     { "path": "src/components/Foo.tsx", "ai": 82, "human": 10, "mixed": 2, "total": 94, "pctAi": 87 }
@@ -428,36 +463,139 @@ To force re-detection of the TypeScript runtime (e.g., after installing Bun): `r
 
 ---
 
-## VP Dashboard (Datadog)
+## Metrics Export
 
-Attribution data is pushed to Datadog automatically on every PR merge via GitHub Actions (`.github/workflows/claude-attribution.yml`). No developer holds the API key — it lives in an org-level GHA secret.
+Attribution metrics are exported automatically on every PR merge via GitHub Actions (`.github/workflows/claude-attribution-export.yml`). The workflow uses the OpenTelemetry OTLP/HTTP JSON format and supports any OTel-compliant backend.
 
-**Metrics pushed on each merged PR:**
+**Metrics exported on each merged PR:**
 
-| Metric | Description |
-|--------|-------------|
-| `claude_attribution.ai_lines` | Lines written by Claude and committed unchanged |
-| `claude_attribution.human_lines` | Lines written or left unchanged by the developer |
-| `claude_attribution.total_lines` | Total committed lines in the PR |
-| `claude_attribution.pct_ai` | Percentage of lines attributed to Claude (this PR) |
-| `claude_attribution.codebase_pct_ai` | Cumulative codebase-wide AI% at PR merge time (requires minimap) |
-| `claude_attribution.codebase_total_lines` | Total codebase lines tracked in the minimap |
-| `github_copilot.acceptance_rate` | Org-level Copilot suggestion acceptance rate |
-| `github_copilot.lines_accepted` | Copilot lines accepted org-wide |
-| `github_copilot.lines_suggested` | Copilot lines suggested org-wide |
+| Metric | Unit | Description |
+|--------|------|-------------|
+| `claude_attribution.ai_lines` | lines | Lines written by Claude and committed unchanged |
+| `claude_attribution.human_lines` | lines | Lines written or left unchanged by the developer |
+| `claude_attribution.total_lines` | lines | Total committed lines in the PR |
+| `claude_attribution.pct_ai` | % | Percentage of lines attributed to Claude (this PR) |
+| `claude_attribution.codebase_pct_ai` | % | Cumulative codebase-wide AI% at PR merge time (requires minimap) |
+| `claude_attribution.codebase_total_lines` | lines | Total codebase lines tracked in the minimap |
+| `claude_attribution.cost_usd` | $ | Estimated Claude API cost for this PR (requires v1.5.0+ notes) |
+| `claude_attribution.input_tokens` | tokens | Total input tokens consumed by Claude in this PR |
+| `claude_attribution.output_tokens` | tokens | Total output tokens generated by Claude in this PR |
+| `claude_attribution.cache_read_tokens` | tokens | Cache read tokens in this PR |
+| `claude_attribution.cache_creation_tokens` | tokens | Cache creation tokens in this PR |
 
-All metrics are tagged `repo:`, `pr:`, `branch:`, `author:`, `tool:` — enabling side-by-side Claude vs. Copilot comparison on a single dashboard.
+Token and cost metrics are only emitted when the git notes contain token data (written by v1.5.0+ hooks). All metrics carry attributes `pr`, `branch`, `author`, `tool` — enabling per-PR trend analysis.
 
-> **Important limitation — Copilot metrics are org-level aggregates, not per-PR or per-developer:**
-> GitHub's Copilot usage API returns org-wide daily totals (suggestions shown, lines accepted, acceptance rate). These are the same numbers regardless of which PR triggered the push. The Copilot rows in Datadog reflect organization-wide Copilot activity at the time of the push — they cannot be scoped to a specific PR, branch, or developer. In contrast, `claude_attribution.*` metrics are per-PR and per-file, derived from git notes written at commit time.
->
-> If you need per-seat or per-repo Copilot breakdowns, use the GitHub Copilot usage dashboard directly. The org-level Copilot numbers here are useful as a trend signal alongside Claude attribution data.
+**Supported backends:**
+
+| Backend | Configuration |
+|---------|---------------|
+| **Datadog** (shortcut) | Set `DATADOG_API_KEY` secret (and optionally `DATADOG_SITE` org variable, defaults to `datadoghq.com`). Endpoint is auto-configured. |
+| **Datadog** (explicit) | `OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.datadoghq.com`, `OTEL_EXPORTER_OTLP_HEADERS=DD-Api-Key=<key>` |
+| **Grafana Cloud** | `OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-<zone>.grafana.net/otlp`, `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic <base64(user:token)>` |
+| **Splunk Observability** | `OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<realm>.signalfx.com/v2/datapoint/otlp`, `OTEL_EXPORTER_OTLP_HEADERS=X-SF-Token=<token>` |
+| **New Relic** | `OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net`, `OTEL_EXPORTER_OTLP_HEADERS=api-key=<key>` |
+| **Honeycomb** | `OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io`, `OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=<key>` |
+| **OTel Collector** | `OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4318` |
+| **Generic webhook** | `METRICS_WEBHOOK_URL=https://...` — POSTs a flat JSON payload with `pr`, `repo`, `author`, `branch`, `ai_lines`, `human_lines`, `total_lines`, `pct_ai`, and optionally `codebase_pct_ai` / `codebase_total_lines` / `cost_usd` / `input_tokens` / `output_tokens` |
+
+When no destination is configured, the workflow runs in **dry-run mode** — it prints the OTLP payload to stdout and exits 0. This makes it safe to install and test before secrets are set.
+
+Set secrets at the org level so they apply to all repos that use this tool. Multiple export destinations can be active simultaneously (e.g. both `OTEL_EXPORTER_OTLP_ENDPOINT` and `METRICS_WEBHOOK_URL`).
+
+**Model pricing (org variables — update when Anthropic changes pricing):**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_PRICE_OPUS_INPUT` | `15.00` | $ per 1M input tokens (Claude Opus) |
+| `CLAUDE_PRICE_OPUS_OUTPUT` | `75.00` | $ per 1M output tokens (Claude Opus) |
+| `CLAUDE_PRICE_SONNET_INPUT` | `3.00` | $ per 1M input tokens (Claude Sonnet) |
+| `CLAUDE_PRICE_SONNET_OUTPUT` | `15.00` | $ per 1M output tokens (Claude Sonnet) |
+| `CLAUDE_PRICE_HAIKU_INPUT` | `0.80` | $ per 1M input tokens (Claude Haiku) |
+| `CLAUDE_PRICE_HAIKU_OUTPUT` | `4.00` | $ per 1M output tokens (Claude Haiku) |
+| `CLAUDE_PRICE_CACHE_READ_MULT` | `0.1` | Fraction of input price for cache reads |
+| `CLAUDE_PRICE_CACHE_WRITE_MULT` | `1.25` | Fraction of input price for cache writes |
+
+Unrecognized model names (new Claude releases) fall back to Opus pricing. Set these as org-level **variables** (not secrets) — they're not sensitive.
+
+
+---
+
+## 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:
 
-**Required secrets (set once at org level):**
-- `DATADOG_API_KEY` — Datadog API key
-- `DATADOG_SITE` variable — e.g. `datadoghq.com`
+### 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   # replace with your self-hosted runner label if needed
+    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
+```
 
-**Future:** When Faros is purchased, ADMPLAT-9609 will provide a Faros pipeline. Switching destinations is a one-line change to `src/export/pr-summary.ts` — the data collection, notes format, and GHA trigger all stay the same.
+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.
 
 ---
 
@@ -504,7 +642,7 @@ Each hook invocation is a short-lived process that exits immediately. The trace
 
 The post-commit hook may not have run. Check:
 1. Is `bun` (or `tsx`) on your PATH in a git hook context? Run `which bun` from your shell, then check if that path is in `.git/hooks/post-commit`.
-2. Did you run `bun src/setup/install.ts <repo>` for this specific repo?
+2. Did you run `claude-attribution install <repo>` for this specific repo?
 3. Check `.claude/logs/attribution.jsonl` — if it's empty, the hook isn't firing.
 
 **Attribution is 0% AI even though Claude wrote everything**

package/package.json

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

package/src/attribution/commit.ts

@@ -34,6 +34,7 @@ import {
 	type LineAttribution,
 	hashLine,
 } from "./differ.ts";
+import { parseTranscript } from "../metrics/transcript.ts";
 import {
 	writeNote,
 	headSha,
@@ -146,6 +147,21 @@ async function main() {
 		totals: aggregateTotals(fileResults),
 	};
 
+	// Attach token usage from the Claude session transcript (non-fatal if unavailable)
+	if (sessionId) {
+		const tx = await parseTranscript(sessionId, repoRoot).catch(() => null);
+		if (tx && tx.byModel.length > 0) {
+			result.modelUsage = tx.byModel.map((m) => ({
+				modelFull: m.modelFull,
+				modelShort: m.modelShort,
+				inputTokens: m.inputTokens,
+				outputTokens: m.outputTokens,
+				cacheCreationTokens: m.cacheCreationTokens,
+				cacheReadTokens: m.cacheReadTokens,
+			}));
+		}
+	}
+
 	// Write git note
 	await writeNote(result, repoRoot);
 

package/src/attribution/differ.ts

@@ -21,6 +21,16 @@ export interface FileAttribution {
 	pctAi: number;
 }
 
+/** Token usage captured from the Claude session transcript at commit time. */
+export interface CommitModelUsage {
+	modelFull: string;
+	modelShort: "Opus" | "Sonnet" | "Haiku" | "Unknown";
+	inputTokens: number;
+	outputTokens: number;
+	cacheCreationTokens: number;
+	cacheReadTokens: number;
+}
+
 export interface AttributionResult {
 	commit: string;
 	/** Session ID from .claude/attribution-state/current-session, or null if committed outside a Claude session. */
@@ -30,6 +40,8 @@ export interface AttributionResult {
 	timestamp: string;
 	files: FileAttribution[];
 	totals: Omit<FileAttribution, "path">;
+	/** Token usage from the Claude session that produced this commit. Absent for commits outside a Claude session or pre-v1.5.0 notes. */
+	modelUsage?: CommitModelUsage[];
 }
 
 /**

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,12 @@ switch (cmd) {
 	case "pr":
 		await import("./commands/pr.ts");
 		break;
+	case "note-ai-commit":
+		await import("./commands/note-ai-commit.ts");
+		break;
+	case "pr-summary":
+		await import("./export/pr-summary.ts");
+		break;
 	case "init":
 		await import("./commands/init.ts");
 		break;
@@ -93,6 +99,8 @@ 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)
+  pr-summary           Export PR attribution metrics via OTLP/webhook (GHA use)
   start            Mark session start for per-ticket scoping
   hook <name>      Run an internal hook (used by installed git hooks)
   version          Print version