claude-attribution 1.0.0

package/README.md

@@ -0,0 +1,431 @@
+# 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
+> 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](https://github.com/organizations/DTS-Productivity-Engineering/settings/copilot/seat_management). 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 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.
+
+---
+
+## For Repo Maintainers: Installing Into a Repo
+
+### Prerequisites
+
+- [Bun](https://bun.sh) is the preferred runtime (`curl -fsSL https://bun.sh/install | bash`)
+- If Bun isn't available, `tsx` also works: `npm install -g tsx`
+  The tool auto-detects the runtime (bun → tsx → npx tsx).
+
+### 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)
+
+**npm install:**
+```bash
+claude-attribution install ~/Code/your-repo
+```
+
+**Clone install:**
+```bash
+bun ~/Code/claude-attribution/src/setup/install.ts ~/Code/your-repo
+```
+
+The installer makes four changes to the target repo:
+
+**`.claude/settings.json`** — merges five Claude Code hooks:
+
+| Event | Hook | What it does |
+|-------|------|--------------|
+| PreToolUse (Edit/Write/MultiEdit/NotebookEdit) | `pre-tool-use.ts` | Snapshot file content before Claude touches it |
+| PostToolUse (all tools) | `post-tool-use.ts` | Snapshot file after Claude writes + log tool call |
+| SubagentStart / SubagentStop | `subagent.ts` | Log subagent activity |
+| Stop | `stop.ts` | No-op; registered for future use |
+
+**`.git/hooks/post-commit`** — runs attribution after every commit. If the repo already has a `post-commit` hook from Husky or another tool, the call is appended rather than replacing it. For Lefthook repos, the installer prints the config snippet to add manually.
+
+**`.git/hooks/pre-push`** — pushes `refs/notes/claude-attribution` to origin whenever you push, so GitHub Actions can read the notes on PR merge. The installer also runs `git config --add remote.origin.push refs/notes/claude-attribution:refs/notes/claude-attribution` so `git push origin` includes notes automatically.
+
+**`.claude/commands/`** — installs two slash commands:
+- `/metrics` — generate a PR metrics report
+- `/start` — mark the start of a new Jira ticket session
+
+**`.gitignore`** — adds `.claude/logs/` so tool usage logs don't end up in version control.
+
+### Committing the settings change
+
+The `.claude/settings.json` change should be committed to the repo so all developers get the hooks automatically. The `.git/hooks/post-commit` hook is local only (`.git/` is not committed) — each developer runs the installer once.
+
+```bash
+# After running the installer:
+git add .claude/settings.json .gitignore
+git commit -m "chore: install claude-attribution hooks"
+```
+
+### Re-installing after moving this directory
+
+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:
+
+```bash
+# npm install:
+claude-attribution install ~/Code/your-repo
+
+# clone install:
+bun src/setup/install.ts ~/Code/your-repo
+```
+
+### Uninstalling
+
+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` and `.git/hooks/pre-push`, and removes the `/metrics` and `/start` slash commands. Attribution state (`.claude/attribution-state/`) and logs (`.claude/logs/`) are left in place.
+
+---
+
+## For Developers: Day-to-Day Usage
+
+### What changes for you
+
+Nothing changes in how you work. The hooks run silently in the background. After each `git commit` you'll see a one-line summary in the terminal:
+
+```
+[claude-attribution] a3f1b2c — 142 AI / 38 human / 4 mixed lines (77% AI)
+```
+
+That's it. No other interaction required.
+
+### Starting a new Jira ticket
+
+When you check out a new branch for a new ticket, run `/start` in Claude Code:
+
+```
+/start
+```
+
+This writes a timestamp to `.claude/attribution-state/session-start`. The `/metrics` command uses this to scope tool counts, token usage, and attribution data to only the activity after this marker — so a long-running Claude Code session doesn't inflate metrics across multiple tickets.
+
+### Creating a PR with metrics
+
+When you're ready to create a PR, use the `/pr` slash command in Claude Code. It collects metrics and creates the PR in one step — no copy-paste needed:
+
+```
+/pr "feat: COMM-1234 add user authentication"
+```
+
+Or run directly:
+
+```bash
+claude-attribution pr "feat: COMM-1234 add user authentication"
+claude-attribution pr "feat: my feature" --draft          # Open as draft
+claude-attribution pr "feat: my feature" --base develop   # Different base branch
+claude-attribution pr                                      # Title from branch name
+```
+
+This reads `.github/PULL_REQUEST_TEMPLATE.md` if it exists, injects the metrics block at a `<!-- claude-attribution metrics -->` placeholder (or appends if missing), and creates the PR via `gh`. Requires `gh` to be installed and authenticated (`gh auth status`).
+
+### Viewing metrics without creating a PR
+
+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:
+
+```markdown
+## Claude Code Metrics
+
+**Session ID:** `abc-123-...`
+
+### Tools Used
+- **Edit:** 47 calls
+- **Read:** 31 calls
+...
+
+### Model Usage
+| Model | API Calls | Input Tokens | Output Tokens | Cache Tokens |
+...
+
+**Human prompts (steering effort):** 12
+
+### Code Attribution
+- **AI-authored lines:** 142
+- **Human-authored lines:** 38
+- **Mixed lines (AI wrote, human modified):** 4
+- **Total committed lines:** 184
+- **AI contribution:** ~77%
+
+#### Files Modified by Claude
+- `src/components/Foo.tsx` — 89% AI (82 lines)
+- `src/hooks/useBar.ts` — 61% AI (44 lines)
+```
+
+### Running with a specific session ID
+
+If you have multiple sessions and want metrics for a specific one:
+
+```bash
+claude-attribution metrics <session-id>
+```
+
+Session IDs are shown in `.claude/logs/tool-usage.jsonl`.
+
+### Checking raw attribution data
+
+Attribution results are stored as git notes and queryable directly:
+
+```bash
+# View attribution for the last commit
+git notes --ref=claude-attribution show HEAD
+
+# List all attributed commits in the repo
+git notes --ref=claude-attribution list
+```
+
+Example output:
+
+```json
+{
+  "commit": "a3f1b2c",
+  "session": "abc-123-...",
+  "branch": "feature/COMM-1234",
+  "timestamp": "2026-03-26T15:32:00.000Z",
+  "files": [
+    { "path": "src/components/Foo.tsx", "ai": 82, "human": 10, "mixed": 2, "total": 94, "pctAi": 87 }
+  ],
+  "totals": { "ai": 142, "human": 38, "mixed": 4, "total": 184, "pctAi": 77 }
+}
+```
+
+---
+
+## How Attribution Works
+
+### The algorithm
+
+Every time Claude writes to a file, two snapshots are captured:
+
+- **Before snapshot** — file content before Claude's *first* edit in the session (saved by the PreToolUse hook, preserved on subsequent edits)
+- **After snapshot** — file content after Claude's *last* edit (saved by the PostToolUse hook, updated on every edit)
+
+After you `git commit`, the post-commit hook runs and compares Claude's **last after-snapshot** for each changed file against what was actually committed, line by line.
+
+Each committed line is classified:
+
+| Label | Rule | Meaning |
+|-------|------|---------|
+| **AI** | Hash in after-snapshot, not in before-snapshot | Claude wrote this line and it survived to the commit unchanged |
+| **HUMAN** | Not in after-snapshot, or existed before Claude touched the file | You wrote it, or it predates the session |
+| **MIXED** | Claude wrote a line at this position but the committed content differs | Claude wrote it, you modified it before committing |
+
+Empty lines are always HUMAN — they carry no attribution signal.
+
+### Worked example
+
+Say a file originally contains two lines:
+
+```
+before: ["const a = 1;", "const b = 2;"]
+```
+
+Claude edits it and the after-snapshot is:
+
+```
+after:  ["const a = 1;", "const b = 2;", "const c = 3;", "export default fn;"]
+```
+
+You then modify `fn` to `main` before committing:
+
+```
+committed: ["const a = 1;", "const b = 2;", "const c = 3;", "export default main;"]
+```
+
+Line-by-line classification:
+
+| Line | Before | After | Committed | Label |
+|------|--------|-------|-----------|-------|
+| `const a = 1;` | ✓ | ✓ | ✓ | **HUMAN** (existed before Claude) |
+| `const b = 2;` | ✓ | ✓ | ✓ | **HUMAN** (existed before Claude) |
+| `const c = 3;` | ✗ | ✓ | ✓ | **AI** (Claude wrote it, committed unchanged) |
+| `export default main;` | ✗ | hash differs (`fn` vs `main`) | ✓ | **MIXED** (Claude wrote `fn`, you changed to `main`) |
+
+Result: 1 AI / 2 HUMAN / 1 MIXED = 25% AI contribution.
+
+### Why this is correct (unlike the previous approach)
+
+The old `calculate-metrics.sh` summed every line Claude ever wrote across all Edit/Write operations and divided by the net git diff. If Claude edited a file four times and you rewrote it entirely, the script claimed ~100% AI. That was wrong.
+
+This tool compares Claude's **final written state** against **what was committed**. If you rewrote it entirely, none of your lines hash-match Claude's snapshot → 0% AI. Correct.
+
+### Multi-commit workflow
+
+Each commit is attributed independently at commit time (when checkpoints are freshest). The `/metrics` command aggregates across all commits on the current branch using "last-write-wins" per file: for files touched in multiple commits, the stats from the most recent commit are used. This represents the final state of each file and prevents double-counting when the same file appears in multiple commits.
+
+Running `/start` scopes both tool/token metrics AND attribution data to commits made after the start marker. Use it when beginning a new Jira ticket to get per-ticket metrics.
+
+---
+
+## Known Limitations
+
+- **Binary files** are skipped (git shows them as binary, content can't be compared line-by-line).
+
+- **Identical-line content** — the algorithm is set-based. Two lines with the same trimmed content produce the same hash. If Claude and a human both write a line like `}` (a closing brace) and `}` didn't exist in the before-snapshot, the tool attributes it as AI regardless of who actually wrote it. This is a conservative bias toward AI for identical content — an acceptable trade-off since lines with identical content are indistinguishable without tracking insertion history.
+
+- **MIXED detection is positional (best-effort)** — MIXED is detected by checking whether Claude's i-th line was changed in the committed file. If a human inserts or deletes lines above position `i`, the commit's line positions shift while the after-snapshot's positions don't, causing false MIXED classifications. MIXED is most accurate when human edits are small in-place tweaks (e.g., changing a value on a line Claude wrote) rather than bulk insertions or deletions.
+
+- **Sessions without checkpoints** — commits made outside an active Claude session (no `current-session` file, or checkpoints already cleaned up) are attributed 100% HUMAN. This is correct.
+
+- **`git commit --amend`** — when a commit is amended, the original SHA is replaced but the old git note (pointing to the now-orphaned SHA) remains in the notes object store. `/metrics` reads notes across the entire branch, so an amended commit's lines may appear twice. Avoid amending published commits; if you do, run `/metrics` knowing totals may be slightly inflated for that commit's files.
+
+- **Multiple sessions on the same branch** — if two different Claude sessions both touch the same file, the last write wins. Only the session whose `after` checkpoint was written most recently contributes to attribution for that file.
+
+- **Hash collisions** — uses a 16-character SHA-256 prefix (2^64 space); collision threshold is ~4 billion unique lines (negligible in practice).
+
+---
+
+## Security Model
+
+- **The package directory is a trusted location** — installed hooks embed an absolute path to `bin/claude-attribution` at install time. Compromise of the package directory would affect all repos that have hooks installed. Keep it in a location with normal user-only permissions (npm global installs and `~/Code/` clones are both fine).
+
+- **`session_id` is validated** — checkpoint paths include the session ID as a directory component. The tool validates session IDs against `[a-zA-Z0-9_-]{1,128}` before use, preventing path traversal attacks.
+
+- **Checkpoint directories are `chmod 0700`** — `/tmp/claude-attribution/<session>/` is created with owner-only read/write so other users on shared machines cannot access file snapshots.
+
+- **`.claude/logs/` is gitignored** — the installer adds `.claude/logs/` to `.gitignore` automatically. Tool usage logs contain session IDs and tool inputs that should not be committed to version control.
+
+---
+
+## Checkpoints and Temp Files
+
+Checkpoints are stored in `/tmp/claude-attribution/<session-id>/` as JSON files. They are intentionally **not** cleaned up when your Claude Code session ends — you may close Claude Code and commit later, and the checkpoints need to survive until you do. The OS clears `/tmp/` on reboot, which is sufficient. Stale checkpoints from old sessions are harmless.
+
+To force re-detection of the TypeScript runtime (e.g., after installing Bun): `rm /tmp/claude-attribution-runtime`
+
+---
+
+## VP Dashboard (Datadog)
+
+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.
+
+**Metrics pushed 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 |
+| `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 |
+
+All metrics are tagged `repo:`, `pr:`, `branch:`, `author:`, `tool:` — enabling side-by-side Claude vs. Copilot comparison on a single dashboard.
+
+> **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.
+
+**Required secrets (set once at org level):**
+- `DATADOG_API_KEY` — Datadog API key
+- `DATADOG_SITE` variable — e.g. `datadoghq.com`
+
+**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.
+
+---
+
+## 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.
+
+### Env vars
+
+| Variable | Required | Example | Description |
+|----------|----------|---------|-------------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Yes (to enable) | `http://localhost:4318` | OTLP/HTTP receiver. Unset = OTel disabled. |
+| `OTEL_EXPORTER_OTLP_HEADERS` | No | `DD-Api-Key=abc123` | Comma-separated `key=value` headers (required for Datadog OTLP intake, not needed for local Agent) |
+| `OTEL_SERVICE_NAME` | No | `claude-code` | Service name in APM. Defaults to `claude-code`. |
+
+**Datadog via local Agent** (Agent with OTLP enabled on port 4318 — no API key needed):
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+```
+
+**Datadog OTLP intake** (direct, without Agent):
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.datadoghq.com
+export OTEL_EXPORTER_OTLP_HEADERS=DD-Api-Key=<your-api-key>
+```
+
+### What gets traced
+
+Two span types are emitted:
+
+**`tool_call/{toolName}`** (child span) — one per tool call. Emitted at the end of each `PostToolUse` hook invocation. Attributes: `tool.name`, `file.path` (if applicable), `session.id`.
+
+**`claude-session`** (root span) — one per commit. Emitted at the end of the `post-commit` hook. Covers `startTime` (first tool call in the session) → commit time. Attributes: `session.id`, `git.branch`, `git.commit`, `attribution.ai_lines`, `attribution.human_lines`, `attribution.mixed_lines`, `attribution.total_lines`, `attribution.pct_ai`.
+
+### How context is persisted
+
+Each hook invocation is a short-lived process that exits immediately. The trace context (`traceId`, `rootSpanId`, `startTime`, etc.) is persisted to `.claude/attribution-state/otel-context.json` and read by each subsequent hook so all spans share the same trace. The context file is deleted when the root session span is exported at commit time.
+
+---
+
+## Troubleshooting
+
+**"No attribution data found" in the metrics output**
+
+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?
+3. Check `.claude/logs/attribution.jsonl` — if it's empty, the hook isn't firing.
+
+**Attribution is 0% AI even though Claude wrote everything**
+
+Most likely the commit happened in a different terminal session from where Claude is running. The `current-session` file in `.claude/attribution-state/` needs to match the session that created the checkpoints. Start Claude, make your changes, and commit without switching sessions.
+
+**The hook is slowing down commits**
+
+The post-commit hook runs attribution after the commit is already recorded — it can't block the commit. If you see a pause, it's likely runtime startup time on a cold start (~100ms for Bun, ~300ms for npx tsx). Subsequent runs use the cached runtime from `/tmp/claude-attribution-runtime` and are faster.
+
+**Runtime cache is stale (wrong runtime used after installing Bun)**
+
+Delete the cache file to force re-detection:
+```bash
+rm /tmp/claude-attribution-runtime
+```

package/bin/claude-attribution

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Resolve symlinks portably (macOS readlink doesn't support -f)
+SELF="$0"
+while [ -L "$SELF" ]; do
+  SELF_DIR="$(cd "$(dirname "$SELF")" && pwd)"
+  SELF="$SELF_DIR/$(readlink "$SELF")"
+done
+PACKAGE_ROOT="$(cd "$(dirname "$SELF")/.." && pwd)"
+exec "$PACKAGE_ROOT/src/run.sh" "$PACKAGE_ROOT/src/cli.ts" "$@"

package/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "claude-attribution",
+	"version": "1.0.0",
+	"description": "AI code attribution tracking for Claude Code sessions — checkpoint-based line diff approach",
+	"type": "module",
+	"bin": {
+		"claude-attribution": "bin/claude-attribution"
+	},
+	"files": [
+		"src/",
+		"bin/"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"install-repo": "bun src/setup/install.ts",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"prepare": "chmod 755 bin/claude-attribution"
+	},
+	"devDependencies": {
+		"bun-types": "^1.3.11",
+		"typescript": "^6.0.2"
+	}
+}