claude-attribution 1.0.0

package/src/metrics/transcript.ts

@@ -0,0 +1,245 @@
+/**
+ * Parse Claude Code transcript files for token and model usage.
+ *
+ * Claude Code writes JSONL transcript files to:
+ *   ~/.claude/projects/<project-key>/<session-id>.jsonl
+ *
+ * where <project-key> is the absolute repo path with '/' replaced by '-'.
+ * Each line is a JSON object with `type: "human" | "assistant" | ...`.
+ * Assistant messages include `message.model` and `message.usage` (token counts).
+ *
+ * Subagent transcripts are stored in:
+ *   ~/.claude/projects/<project-key>/<session-id>/subagents/<agent-id>.jsonl
+ *
+ * This module reads both main and subagent transcripts, merges them by model,
+ * and returns aggregated token/model usage + human prompt count.
+ */
+import { readFile, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+import { homedir } from "os";
+
+export interface ModelUsage {
+	modelShort: "Opus" | "Sonnet" | "Haiku" | "Unknown";
+	modelFull: string;
+	calls: number;
+	inputTokens: number;
+	outputTokens: number;
+	cacheCreationTokens: number;
+	cacheReadTokens: number;
+}
+
+export interface TranscriptResult {
+	sessionId: string;
+	byModel: ModelUsage[];
+	totals: {
+		totalCalls: number;
+		totalInputTokens: number;
+		totalOutputTokens: number;
+		totalCacheCreationTokens: number;
+		totalCacheReadTokens: number;
+	};
+	humanPromptCount: number;
+	/** Active session time in minutes (idle gaps >15 min are excluded). */
+	activeMinutes: number;
+}
+
+interface TranscriptEntry {
+	type?: string;
+	timestamp?: string;
+	message?: {
+		model?: string;
+		usage?: {
+			input_tokens?: number;
+			output_tokens?: number;
+			cache_creation_input_tokens?: number;
+			cache_read_input_tokens?: number;
+		};
+	};
+}
+
+function modelShort(full: string): ModelUsage["modelShort"] {
+	if (/opus/i.test(full)) return "Opus";
+	if (/sonnet/i.test(full)) return "Sonnet";
+	if (/haiku/i.test(full)) return "Haiku";
+	return "Unknown";
+}
+
+/**
+ * Derive the Claude Code projects directory key from an absolute repo path.
+ *
+ * Claude Code stores transcripts at `~/.claude/projects/<key>/` where <key>
+ * is the absolute path with every '/' replaced by '-'. For example:
+ *   /Users/alice/Code/my-repo → -Users-alice-Code-my-repo
+ *
+ * This key is used to locate the transcript JSONL file for a given session.
+ */
+function projectKey(repoRoot: string): string {
+	// Claude Code replaces '/' with '-' in the path
+	return repoRoot.replace(/\//g, "-");
+}
+
+async function parseTranscriptFile(filePath: string): Promise<{
+	entries: TranscriptEntry[];
+	humanCount: number;
+	timestamps: number[];
+}> {
+	const raw = await readFile(filePath, "utf8");
+	const entries: TranscriptEntry[] = [];
+	let humanCount = 0;
+	const timestamps: number[] = [];
+
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			const entry = JSON.parse(trimmed) as TranscriptEntry;
+			entries.push(entry);
+			if (entry.type === "human") humanCount++;
+			if (entry.timestamp) {
+				const ms = new Date(entry.timestamp).getTime();
+				if (!isNaN(ms)) timestamps.push(ms);
+			}
+		} catch {
+			// Skip malformed lines
+		}
+	}
+
+	return { entries, humanCount, timestamps };
+}
+
+/**
+ * Compute active session time in minutes from a sorted list of timestamps.
+ *
+ * Sums consecutive gaps only when the gap is under 15 minutes (900_000ms).
+ * Gaps of 15+ minutes are treated as idle (away from keyboard, blocked on CI,
+ * etc.) and excluded so they don't inflate the active time metric.
+ */
+function computeActiveMinutes(allTimestamps: number[]): number {
+	const sorted = [...allTimestamps].sort((a, b) => a - b);
+	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];
+		if (gap < IDLE_THRESHOLD_MS) totalMs += gap;
+	}
+	return Math.round(totalMs / 60_000);
+}
+
+function aggregateEntries(entries: TranscriptEntry[]): Map<string, ModelUsage> {
+	const byModel = new Map<string, ModelUsage>();
+
+	for (const entry of entries) {
+		if (entry.type !== "assistant") continue;
+		const model = entry.message?.model;
+		const usage = entry.message?.usage;
+		if (!model || !usage) continue;
+
+		const existing = byModel.get(model) ?? {
+			modelShort: modelShort(model),
+			modelFull: model,
+			calls: 0,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheCreationTokens: 0,
+			cacheReadTokens: 0,
+		};
+
+		existing.calls++;
+		existing.inputTokens += usage.input_tokens ?? 0;
+		existing.outputTokens += usage.output_tokens ?? 0;
+		existing.cacheCreationTokens += usage.cache_creation_input_tokens ?? 0;
+		existing.cacheReadTokens += usage.cache_read_input_tokens ?? 0;
+
+		byModel.set(model, existing);
+	}
+
+	return byModel;
+}
+
+/**
+ * Parse transcript data for a session, merging main and subagent token usage.
+ *
+ * Reads the main session transcript and all subagent transcripts from the
+ * ~/.claude/projects/<key>/ directory structure. Aggregates token counts by model
+ * (Opus / Sonnet / Haiku / Unknown) and counts human prompt turns.
+ *
+ * Human prompt count is used as a proxy for "steering effort" in the /metrics output
+ * — it represents how many times the developer had to direct Claude.
+ *
+ * Returns null if the session transcript file doesn't exist (session not found).
+ */
+export async function parseTranscript(
+	sessionId: string,
+	repoRoot?: string,
+): Promise<TranscriptResult | null> {
+	const root = repoRoot ?? resolve(process.cwd());
+	const key = projectKey(root);
+	const transcriptDir = join(homedir(), ".claude", "projects", key);
+	const mainFile = join(transcriptDir, `${sessionId}.jsonl`);
+
+	if (!existsSync(mainFile)) return null;
+
+	const {
+		entries: mainEntries,
+		humanCount,
+		timestamps: mainTimestamps,
+	} = await parseTranscriptFile(mainFile);
+	const combined = aggregateEntries(mainEntries);
+	const allTimestamps: number[] = [...mainTimestamps];
+
+	// Merge subagent transcripts
+	const subagentDir = join(transcriptDir, sessionId, "subagents");
+	if (existsSync(subagentDir)) {
+		for (const file of (await readdir(subagentDir)).filter((f) =>
+			f.endsWith(".jsonl"),
+		)) {
+			const { entries, timestamps } = await parseTranscriptFile(
+				join(subagentDir, file),
+			);
+			allTimestamps.push(...timestamps);
+			for (const [model, usage] of aggregateEntries(entries)) {
+				const existing = combined.get(model);
+				if (!existing) {
+					combined.set(model, usage);
+				} else {
+					existing.calls += usage.calls;
+					existing.inputTokens += usage.inputTokens;
+					existing.outputTokens += usage.outputTokens;
+					existing.cacheCreationTokens += usage.cacheCreationTokens;
+					existing.cacheReadTokens += usage.cacheReadTokens;
+				}
+			}
+		}
+	}
+
+	const byModel = [...combined.values()].sort((a, b) =>
+		a.modelShort.localeCompare(b.modelShort),
+	);
+
+	const totals = byModel.reduce(
+		(acc, m) => ({
+			totalCalls: acc.totalCalls + m.calls,
+			totalInputTokens: acc.totalInputTokens + m.inputTokens,
+			totalOutputTokens: acc.totalOutputTokens + m.outputTokens,
+			totalCacheCreationTokens:
+				acc.totalCacheCreationTokens + m.cacheCreationTokens,
+			totalCacheReadTokens: acc.totalCacheReadTokens + m.cacheReadTokens,
+		}),
+		{
+			totalCalls: 0,
+			totalInputTokens: 0,
+			totalOutputTokens: 0,
+			totalCacheCreationTokens: 0,
+			totalCacheReadTokens: 0,
+		},
+	);
+
+	return {
+		sessionId,
+		byModel,
+		totals,
+		humanPromptCount: humanCount,
+		activeMinutes: computeActiveMinutes(allTimestamps),
+	};
+}

package/src/run.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+# TypeScript runtime detector: try bun, then tsx, then npx tsx (no install required).
+#
+# Caches the detected runtime to /tmp/claude-attribution-runtime so that the
+# `command -v` probe only runs once per machine reboot instead of on every hook
+# invocation (hooks run on every Claude Code tool call).
+#
+# To force re-detection (e.g., after installing bun): rm /tmp/claude-attribution-runtime
+CACHE="/tmp/claude-attribution-runtime"
+if [ ! -f "$CACHE" ]; then
+  if command -v bun >/dev/null 2>&1; then
+    echo "bun" > "$CACHE"
+  elif command -v tsx >/dev/null 2>&1; then
+    echo "tsx" > "$CACHE"
+  else
+    echo "npx_tsx" > "$CACHE"
+  fi
+fi
+RUNTIME=$(cat "$CACHE")
+case "$RUNTIME" in
+  bun)     exec bun "$@" ;;
+  tsx)     exec tsx "$@" ;;
+  npx_tsx) exec npx --yes tsx "$@" ;;
+  *)       exec bun "$@" ;;
+esac

package/src/setup/install.ts

@@ -0,0 +1,321 @@
+/**
+ * Installer — run once per repo to add claude-attribution hooks.
+ *
+ * Usage: bun src/setup/install.ts [/path/to/target-repo]
+ *
+ * If no path is given, installs into the current working directory.
+ */
+import {
+	readFile,
+	writeFile,
+	appendFile,
+	copyFile,
+	chmod,
+	mkdir,
+} from "fs/promises";
+import { existsSync } from "fs";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { resolve, join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const execFileAsync = promisify(execFile);
+
+const ATTRIBUTION_ROOT = resolve(
+	dirname(fileURLToPath(import.meta.url)),
+	"..",
+	"..",
+);
+const CLI_BIN = resolve(ATTRIBUTION_ROOT, "bin", "claude-attribution");
+
+interface HookEntry {
+	matcher: string;
+	hooks: Array<{ type: string; command: string }>;
+}
+
+type HooksConfig = Record<string, HookEntry[]>;
+
+interface ClaudeSettings {
+	hooks?: HooksConfig;
+	[key: string]: unknown;
+}
+
+async function mergeHooks(
+	settingsPath: string,
+	newHooks: HooksConfig,
+): Promise<void> {
+	let settings: ClaudeSettings = {};
+	if (existsSync(settingsPath)) {
+		const raw = await readFile(settingsPath, "utf8");
+		settings = JSON.parse(raw) as ClaudeSettings;
+	}
+
+	const existing = settings.hooks ?? {};
+
+	for (const [event, entries] of Object.entries(newHooks)) {
+		const current = existing[event] ?? [];
+		// Remove any existing claude-attribution entries, then push all new ones
+		const filtered = current.filter(
+			(e) => !e.hooks.some((h) => h.command.includes("claude-attribution")),
+		);
+		filtered.push(...entries);
+		existing[event] = filtered;
+	}
+
+	settings.hooks = existing;
+	await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+}
+
+/**
+ * Detect whether the repo uses Husky or Lefthook to manage git hooks.
+ * These tools own .git/hooks/ themselves — we must not write there directly.
+ * Instead we register via their config files.
+ */
+function detectHookManager(repoRoot: string): "husky" | "lefthook" | "none" {
+	if (existsSync(join(repoRoot, ".husky"))) return "husky";
+	if (
+		existsSync(join(repoRoot, "lefthook.yml")) ||
+		existsSync(join(repoRoot, "lefthook.yaml")) ||
+		existsSync(join(repoRoot, "lefthook.json")) ||
+		existsSync(join(repoRoot, ".lefthook.yml")) ||
+		existsSync(join(repoRoot, ".lefthook.json"))
+	)
+		return "lefthook";
+	return "none";
+}
+
+async function installPrePushHook(repoRoot: string): Promise<void> {
+	const manager = detectHookManager(repoRoot);
+	const runLine = `"${CLI_BIN}" hook pre-push || true`;
+
+	if (manager === "husky") {
+		const huskyHook = join(repoRoot, ".husky", "pre-push");
+		if (existsSync(huskyHook)) {
+			const existing = await readFile(huskyHook, "utf8");
+			if (!existing.includes("claude-attribution")) {
+				await writeFile(
+					huskyHook,
+					existing.trimEnd() + "\n\n# claude-attribution\n" + runLine + "\n",
+				);
+				console.log("  (appended to existing .husky/pre-push)");
+			}
+		} else {
+			await writeFile(
+				huskyHook,
+				`#!/bin/sh\n# claude-attribution\n${runLine}\n`,
+			);
+			await chmod(huskyHook, 0o755);
+		}
+		return;
+	}
+
+	if (manager === "lefthook") {
+		console.log("");
+		console.log("  ⚠️  Lefthook detected. Add this to lefthook.yml manually:");
+		console.log("  pre-push:");
+		console.log("    commands:");
+		console.log("      claude-attribution:");
+		console.log(`        run: ${runLine}`);
+		console.log("");
+		return;
+	}
+
+	// Plain git hooks
+	const hookDest = join(repoRoot, ".git", "hooks", "pre-push");
+	const rawTemplate = await readFile(
+		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "pre-push.sh"),
+		"utf8",
+	);
+	const template = rawTemplate.replace(/\{\{CLI_BIN\}\}/g, () => CLI_BIN);
+
+	if (existsSync(hookDest)) {
+		const existing = await readFile(hookDest, "utf8");
+		if (!existing.includes("claude-attribution")) {
+			await writeFile(
+				hookDest,
+				existing.trimEnd() + "\n\n# claude-attribution\n" + template,
+			);
+			await chmod(hookDest, 0o755);
+			return;
+		}
+		// Already ours — replace
+	}
+
+	await writeFile(hookDest, template);
+	await chmod(hookDest, 0o755);
+}
+
+async function installGitHook(repoRoot: string): Promise<void> {
+	const manager = detectHookManager(repoRoot);
+	const runLine = `"${CLI_BIN}" hook post-commit || true`;
+
+	if (manager === "husky") {
+		// Husky: add post-commit file to .husky/ directory
+		const huskyHook = join(repoRoot, ".husky", "post-commit");
+		if (existsSync(huskyHook)) {
+			const existing = await readFile(huskyHook, "utf8");
+			if (!existing.includes("claude-attribution")) {
+				await writeFile(
+					huskyHook,
+					existing.trimEnd() + "\n\n# claude-attribution\n" + runLine + "\n",
+				);
+				console.log("  (appended to existing .husky/post-commit)");
+			}
+		} else {
+			await writeFile(
+				huskyHook,
+				`#!/bin/sh\n# claude-attribution\n${runLine}\n`,
+			);
+			await chmod(huskyHook, 0o755);
+		}
+		return;
+	}
+
+	if (manager === "lefthook") {
+		// Lefthook: instruct the user — auto-editing YAML is fragile
+		console.log("");
+		console.log("  ⚠️  Lefthook detected. Add this to lefthook.yml manually:");
+		console.log("  post-commit:");
+		console.log("    commands:");
+		console.log("      claude-attribution:");
+		console.log(`        run: ${runLine}`);
+		console.log("");
+		return;
+	}
+
+	// Plain git hooks
+	const hookDest = join(repoRoot, ".git", "hooks", "post-commit");
+	const template = await readFile(
+		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "post-commit.sh"),
+		"utf8",
+	);
+	const newContent = template.replace(/\{\{CLI_BIN\}\}/g, () => CLI_BIN);
+
+	if (existsSync(hookDest)) {
+		const existing = await readFile(hookDest, "utf8");
+		if (!existing.includes("claude-attribution")) {
+			await writeFile(
+				hookDest,
+				existing.trimEnd() + "\n\n# claude-attribution\n" + newContent,
+			);
+			await chmod(hookDest, 0o755);
+			return;
+		}
+		// Already ours — replace
+	}
+
+	await writeFile(hookDest, newContent);
+	await chmod(hookDest, 0o755);
+}
+
+async function main() {
+	const targetRepo = resolve(process.argv[2] ?? process.cwd());
+
+	if (!existsSync(join(targetRepo, ".git"))) {
+		console.error(`Error: ${targetRepo} is not a git repository`);
+		process.exit(1);
+	}
+
+	console.log(`Installing claude-attribution into: ${targetRepo}`);
+	console.log(`CLI binary: ${CLI_BIN}`);
+
+	// 1. Merge hooks into .claude/settings.json
+	const claudeDir = join(targetRepo, ".claude");
+	await mkdir(claudeDir, { recursive: true });
+	await mkdir(join(claudeDir, "attribution-state"), { recursive: true });
+	await mkdir(join(claudeDir, "logs", "sessions"), { recursive: true });
+
+	// Ensure .claude/logs/ is gitignored — tool usage logs contain session data
+	// that shouldn't land in version control.
+	const gitignorePath = join(targetRepo, ".gitignore");
+	const existingGitignore = existsSync(gitignorePath)
+		? await readFile(gitignorePath, "utf8")
+		: "";
+	if (!existingGitignore.includes(".claude/logs")) {
+		const prefix = existingGitignore.endsWith("\n") ? "" : "\n";
+		await appendFile(
+			gitignorePath,
+			`${prefix}# claude-attribution tool usage logs\n.claude/logs/\n`,
+		);
+		console.log("✓ Added .claude/logs/ to .gitignore");
+	}
+
+	const settingsPath = join(claudeDir, "settings.json");
+	const hooksTemplate = await readFile(
+		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "hooks.json"),
+		"utf8",
+	);
+	const hooksConfig = JSON.parse(
+		hooksTemplate.replace(/\{\{CLI_BIN\}\}/g, () => CLI_BIN),
+	) as HooksConfig;
+
+	await mergeHooks(settingsPath, hooksConfig);
+	console.log("✓ Merged hooks into .claude/settings.json");
+
+	// 2. Install post-commit and pre-push git hooks
+	await installGitHook(targetRepo);
+	console.log("✓ Installed .git/hooks/post-commit");
+	await installPrePushHook(targetRepo);
+	console.log(
+		"✓ Installed .git/hooks/pre-push (pushes attribution notes to origin)",
+	);
+
+	// Ensure git push also pushes notes by default
+	try {
+		await execFileAsync(
+			"git",
+			[
+				"config",
+				"--add",
+				"remote.origin.push",
+				"refs/notes/claude-attribution:refs/notes/claude-attribution",
+			],
+			{ cwd: targetRepo },
+		);
+		console.log(
+			"✓ Configured remote.origin.push for attribution notes refspec",
+		);
+	} catch {
+		console.log(
+			"  (skipped git config remote.origin.push — no origin remote or git unavailable)",
+		);
+	}
+
+	// 3. Install /metrics slash command
+	const commandsDir = join(claudeDir, "commands");
+	await mkdir(commandsDir, { recursive: true });
+	const metricsTemplate = await readFile(
+		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "metrics-command.md"),
+		"utf8",
+	);
+	const metricsContent = metricsTemplate.replace(
+		/\{\{CLI_BIN\}\}/g,
+		() => CLI_BIN,
+	);
+	await writeFile(join(commandsDir, "metrics.md"), metricsContent);
+	console.log("✓ Installed .claude/commands/metrics.md (/metrics command)");
+
+	const startTemplate = await readFile(
+		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "start-command.md"),
+		"utf8",
+	);
+	const startContent = startTemplate.replace(/\{\{CLI_BIN\}\}/g, () => CLI_BIN);
+	await writeFile(join(commandsDir, "start.md"), startContent);
+	console.log("✓ Installed .claude/commands/start.md (/start command)");
+
+	const prTemplate = await readFile(
+		join(ATTRIBUTION_ROOT, "src", "setup", "templates", "pr-command.md"),
+		"utf8",
+	);
+	const prContent = prTemplate.replace(/\{\{CLI_BIN\}\}/g, () => CLI_BIN);
+	await writeFile(join(commandsDir, "pr.md"), prContent);
+	console.log("✓ Installed .claude/commands/pr.md (/pr command)");
+
+	console.log("\nDone! claude-attribution is active for this repo.");
+	console.log("Use /pr in Claude Code to create a PR with metrics embedded.");
+}
+
+main().catch((err) => {
+	console.error("Installation failed:", err);
+	process.exit(1);
+});

package/src/setup/templates/hooks.json

@@ -0,0 +1,57 @@
+{
+	"PreToolUse": [
+		{
+			"matcher": "Edit|Write|MultiEdit|NotebookEdit",
+			"hooks": [
+				{
+					"type": "command",
+					"command": "\"{{CLI_BIN}}\" hook pre-tool-use"
+				}
+			]
+		}
+	],
+	"PostToolUse": [
+		{
+			"matcher": ".*",
+			"hooks": [
+				{
+					"type": "command",
+					"command": "\"{{CLI_BIN}}\" hook post-tool-use"
+				}
+			]
+		}
+	],
+	"SubagentStart": [
+		{
+			"matcher": ".*",
+			"hooks": [
+				{
+					"type": "command",
+					"command": "\"{{CLI_BIN}}\" hook subagent"
+				}
+			]
+		}
+	],
+	"SubagentStop": [
+		{
+			"matcher": ".*",
+			"hooks": [
+				{
+					"type": "command",
+					"command": "\"{{CLI_BIN}}\" hook subagent"
+				}
+			]
+		}
+	],
+	"Stop": [
+		{
+			"matcher": ".*",
+			"hooks": [
+				{
+					"type": "command",
+					"command": "\"{{CLI_BIN}}\" hook stop"
+				}
+			]
+		}
+	]
+}

package/src/setup/templates/metrics-command.md

@@ -0,0 +1,27 @@
+# Generate Claude Code Metrics
+
+Generate session metrics for PR documentation.
+
+## Instructions
+
+Run the metrics calculator:
+
+```bash
+"{{CLI_BIN}}" metrics
+```
+
+This outputs PR-ready markdown covering:
+- **Tools Used** — all tool invocations by count
+- **Agents/Skills** — subagent invocations
+- **Model Usage** — API calls and tokens by model
+- **Human prompts** — count of human turns (steering effort proxy)
+- **Code Attribution** — AI / human / mixed line counts from git notes (accurate, not gross write counts)
+- **Files Modified** — per-file AI %
+
+To run with a specific session ID:
+
+```bash
+"{{CLI_BIN}}" metrics <session-id>
+```
+
+Session IDs are in `.claude/logs/tool-usage.jsonl`.

package/src/setup/templates/post-commit.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Auto-installed by claude-attribution
+# Runs attribution analysis after each git commit
+"{{CLI_BIN}}" hook post-commit || true