Coauthor - Feature Spec

One-liner: Point Coauthor at a GitHub repo and get a report of how much of the code that exists today was written by humans versus specific AI tools (Claude, Codex, Copilot, Gemini, Mindlap, other AI), broken down by author, file type, and time.

---

What this project is

Coauthor is a web app that measures the AI-vs-human authorship of a codebase. You give it a GitHub repository URL (and optionally a branch and a personal access token for private repos); it clones the repo, runs line-level git blame on the current state of the code, classifies every line's author into a source bucket - human, or a specific AI tool such as Claude, Codex, Copilot, Gemini, or the Mindlap factory - and renders an interactive report: headline share, a donut, a timeline, a file-type breakdown, a per-developer table, and drill-in evidence for every AI attribution.

The problem it solves

AI coding assistants now write a large and fast-growing share of production code, but that contribution is invisible. Standard tools don't answer the questions teams actually have:

• How much of our shipped codebase is AI-generated - today, not in aggregate over history? Commit counts and additive "lines ever written" stats lie: churned-away code and re-written lines inflate them. What matters is the code that survives in the repo right now.
• Which tools, and which people? "AI wrote X%" is too coarse. Teams want to know which assistants (Claude vs Copilot vs Codex vs an internal factory) and which developers lean on them, and how much.
• Can we trust the number? A percentage with no receipts is unconvincing. Every attribution needs traceable evidence - the commit, the matched signal (email, name, or Co-Authored-By: trailer).
• Without standing up infrastructure. No agent installed in every repo, no database of history, no data retention. Just point it at a repo and get an answer.

Why it was built

• Attribution that reflects reality. Coauthor uses last-touch blame on the current tree rather than summing historical diffs, so the report reflects the code that exists today - the honest denominator for "how much of this is AI."
• Tool- and person-level granularity. Classification distinguishes individual AI sources and preserves each human developer's row (with an ai_assisted count), so the report supports real conversations about how a team works, not just a single vanity metric.
• Trust through evidence. Every AI-bucketed line traces back to a commit and the exact rule that matched it, surfaced in an evidence drawer - the number is auditable, not asserted.
• Zero-footprint by design. The backend is stateless and ephemeral: it clones, analyses, returns the report, and deletes the working copy. No database, no history store, PATs scrubbed from logs and remotes - so it's safe to run against private repositories.

Who it's for

Engineering leaders, factory/platform teams, and developers who want an honest, tool-aware, evidence-backed picture of how much of a codebase is AI-authored - to track AI adoption, report on it, or simply understand where the code is coming from.

---

1. Architecture

• Backend - FastAPI (Python >=3.11). Stateless: no database, no queue, no job persistence. A single synchronous request runs the entire pipeline in-process and returns the full report inline.
• Frontend - React 18 + Vite + TypeScript, TanStack Query, Recharts, Tailwind (Halo design-system tokens). Calls the backend through a typed SDK generated from the backend's OpenAPI schema (frontend/src/client/, committed to the repo).
• Deploy - Single container to Cloud Run. FastAPI serves /api/* and the built SPA from the same origin (frontend/dist mounted when present).

---

2. Core mechanism

The product logic lives in backend/app/analyzer/.

1. Clone - Shallow, single-branch clone of the target repo into a temp directory (cloner.py). The directory is rmtree'd after analysis; nothing persists.
2. Blame, not log - For every non-excluded file at the branch tip, run git blame -w -M -C --line-porcelain to attribute each currently-existing line to its last-touch commit (blamer.py). This answers "what fraction of today's code is AI-written" rather than "how much line-effort happened over time."
3. Classify - Each commit identity is mapped to a bucket via regex rules on author name/email (classifier.py), evaluated in priority order: mindlap -> claude -> codex -> gemini -> copilot -> other_ai (cursor / devin / sweep / replit) -> human (fallback). Matches on email (e.g. noreply@anthropic.com), name (e.g. claude), and Co-Authored-By: trailers. Mindlap is checked first so a Mindlap-factory commit co-authored by a raw model is credited to the factory.
4. Effective identity - If a human authored a commit but an AI is a co-author, the line is credited to the AI bucket, while the developer row stays with the human and records an ai_assisted line count.
5. Branch-diff mode - If the analyzed branch is not the repo default, only lines whose last-touch commit is unique to base..branch are counted. This answers "what did this branch contribute?" instead of counting its whole inherited history. Falls back to full-history blame if the base ref can't be resolved.

---

3. Filtering

filters.py excludes noise before aggregation:

• Lockfiles - package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock, Cargo.lock, go.sum, etc.
• Binaries - images, fonts, media, archives, documents (by extension).
• Vendor / build dirs - node_modules/, vendor/, dist/, build/, .next/, target/, __pycache__/, .eggs/.
• Generated globs - *.min.js, *.min.css, *.map, *.tsbuildinfo, *.egg-info/**.
• .gitignore matches in the target repo.

---

4. API

• Auth - Optional GitHub PAT (ghp_... or github_pat_...), wrapped in SecretStr and scrubbed from logs and git remotes. Public repos analyse anonymously.
• Error shape - {"error": {"code", "message"}}; FastAPI 422 validation surfaces as {"detail": [...]}.
• OpenAPI - Disabled in production (openapi_url=None in main.py); temporarily re-enabled locally to regenerate the SDK.

---

5. Report payload -> UI panels

The ReportResponse payload drives these panels (frontend/src/components/report/):

• KpiRow - Headline totals and AI-vs-human share.
• AiVsHumanDonut - Bucket split of total lines.
• TimelineChart - Daily lines per bucket, re-bucketed into day/week/month bars across 1w-1y ranges.
• FileTypeBars - Added lines per file extension, split by bucket.
• AuthorBreakdown - Per-developer rows (lines, commits, ai_assisted, bucket badge, bot flag); sortable, paginated (25/page), with drill-in to evidence.
• SourceContributionPanel - Per-developer AI-tool usage over 24h / 3d / 7d / 30d windows ("factory contribution").
• EvidenceDrawer - Sample commits with the matched classifier rule (the why behind each bucket).
• Export - Report -> PDF (html2canvas + jsPDF).

States handled: loading skeleton, empty (0 analysable commits), no-AI-activity, and error. The report is cached in sessionStorage keyed by job ID.

---

6. Buckets

---

7. Design decisions & caveats

• Last-touch attribution - A refactor re-credits touched lines to the refactorer, not the original author. Documented tradeoff.
• Identity dedupe - Keyed on lowercased email (falls back to name), so one person committing under multiple user.name values collapses into a single row.
• Fully ephemeral - Every request re-clones and re-analyses; nothing is stored server-side between requests.
• PAT safety - Tokens never touch logs or the on-disk remote (scrubbed in cloner.py + log_filter.py).

---

8. Local run

# Backend (default port 8000)
cd backend && uv venv && uv pip install -e ".[dev]"
.venv/bin/uvicorn app.main:app --reload --port 8000

# Frontend (port 5173)
cd frontend && pnpm install && pnpm run dev

The frontend targets http://localhost:8000 in dev; override with VITE_API_BASE_URL if the backend runs on a different port.