blame-ai

AI-powered git archaeology. Understand why any line exists.

The Problem

git blame tells you WHO wrote the line. It doesn't tell you WHY. You're staring at a magic number, a weird conditional, a function that does one suspiciously specific thing — and the commit message says "fix." blame-ai reads the full commit history, the diff, the surrounding context, and the original PR to explain the actual story behind any line of code.

Quick Start

export ANTHROPIC_API_KEY=sk-ant-...

# Why does this specific line exist?
npx blame-ai src/auth/middleware.ts 15

# Explain a range of lines
npx blame-ai src/auth/middleware.ts --range 15-30

# Why does this entire file exist?
npx blame-ai --why src/auth/middleware.ts

# Full evolution story from first commit to now
npx blame-ai --history src/auth/middleware.ts

Example Output

blame-ai — AI Git Archaeology
────────────────────────────────────────────────────────────────
  src/middleware/auth.ts
  lines 15-22
────────────────────────────────────────────────────────────────

Code Context
────────────────────────────────────────────────────────────────
  15 │ const token = req.headers.authorization?.split(' ')[1]
     └─ @alice · 2025-11-03 · a1b2c3d
  18 │ if (!token) return res.status(401).json({ error: 'No token' })
     └─ @bob · 2025-12-15 · d4e5f6g

AI Archaeology
────────────────────────────────────────────────────────────────

Lines 15-22 form the core of the JWT authentication middleware,
written by Alice on November 3rd as part of the initial auth
rollout (commit a1b2c3d: "feat: add JWT auth middleware").

The optional chaining on line 15 (?.) is defensive — Alice added
it knowing the Authorization header might be absent or malformed
in early integration testing with the mobile team.

Line 18 was updated by Bob on December 15th (commit d4e5f6g:
"fix: return JSON error instead of plain text"). The original
returned a plain-text 401 string. The frontend team reported
JSON.parse errors in their error handler — Bob standardised the
error contract across all API endpoints in this PR.

────────────────────────────────────────────────────────────────
Confidence: High (based on 23 commits of history)

Features

• Line-level archaeology — explain any single line or range with full history
• File-level WHY — understand why an entire file exists in the codebase
• Evolution timeline — trace how a file changed from first commit to now
• Commit + PR context — reads messages, diffs, and linked issues
• Confidence scoring — tells you how much history it had to work with
• Works on any git repo — language-agnostic, runs anywhere with git history

How It Works

1. Runs git blame on the target lines to get per-line commit SHAs
2. Fetches the full commit messages, diffs, and author context for each SHA
3. Reads the surrounding code for additional context
4. Sends everything to Claude with a focused archaeology prompt
5. Returns a plain-English story explaining why the code exists

Requirements

• Node.js 18+
• ANTHROPIC_API_KEY environment variable
• Must be run inside a git repository with commit history

All Commands

Command	Description
blame-ai <file> <line>	Explain a specific line
blame-ai <file> --range 10-20	Explain a range of lines
blame-ai --why <file>	Why does this file exist?
blame-ai --history <file>	Full evolution story

# Install globally if you use it often
npm install -g blame-ai
blame-ai src/something.ts 42

See Also

• repo-whisperer — Talk to any codebase in plain English
• pr-poet — AI-written PR descriptions that actually make sense
• dev-journal — Auto daily dev journal from your git activity

License

MIT — NickCirv