Sourcebook

sourcebook

Catches the files your AI agent forgot to change.

A safety layer for code changes. sourcebook analyzes git diffs for completeness — flags files that should've been modified but weren't. Rules-based structural detection plus AI-powered semantic analysis. Zero false positives on clean diffs.

npx sourcebook init          # sets up Claude Code hooks + generates CLAUDE.md
npx sourcebook check         # check your current diff for missing files
npx sourcebook scan-history  # see what you've been missing

What It Catches

Your AI agent changed the handler. Did it update the test? The sibling module? The config that references the old value?

sourcebook checks your diff against the repo's actual structure:

• Missing test files — source file changed, test file didn't
• Sibling modules — files that import or are imported by what you changed
• Co-change companions — files that historically change together in git commits
• Hub file blast radius — you touched something with 50+ dependents

With --ai: cross-module semantic relationships, field renames that need migrations, stale validation logic.

Key Stats

Metric	Result
Completeness gate	100% accurate (30/30 diffs)
False positive rate	0% on clean diffs
Test file detection	73%
Sibling detection	71%
AI analysis cost	~$0.012/run

Four Surfaces

1. CLI

Run it on any diff. No setup required.

npx sourcebook check              # check staged/unstaged changes
npx sourcebook check --ai         # add AI semantic analysis (requires ANTHROPIC_API_KEY)
npx sourcebook check --quiet      # exit code only (for CI/scripts)
npx sourcebook check --branch main  # compare vs a branch

2. Claude Code Hooks

One command wires up pre-commit hooks. Agent edits a file, sourcebook checks the diff, agent sees what's missing — all before the commit lands.

npx sourcebook init   # generates CLAUDE.md + installs hooks

3. MCP Server

Published on the official MCP registry. Agents can query repo structure, blast radius, conventions, and co-change data on demand.

npx sourcebook serve

Add to your MCP client:

{
  "mcpServers": {
    "sourcebook": {
      "command": "npx",
      "args": ["-y", "sourcebook", "serve", "--dir", "/path/to/your/project"]
    }
  }
}

4. GitHub App (coming soon)

Automated completeness checks on every pull request. Join the waitlist.

Commands

Command	Description
sourcebook check	Analyze current diff for completeness
sourcebook check --ai	Add AI-powered semantic analysis (requires ANTHROPIC_API_KEY)
sourcebook check --quiet	Exit code only — 1 if findings, 0 if clean
sourcebook check --json	Structured JSON output
sourcebook check --branch main	Compare HEAD against a branch
sourcebook check --threshold 0.9	Custom co-change coupling threshold (0-1)
sourcebook init	Set up Claude Code hooks + generate CLAUDE.md/AGENTS.md
sourcebook scan-history	Retrospective scan of recent commits
sourcebook hooks	Install or check Claude Code hooks
sourcebook truth	Generate a Repo Truth Map (2.5D visualization)
sourcebook serve	Start MCP server
sourcebook update	Re-analyze while preserving manual edits
sourcebook diff	Show what would change (exit code 1 if changes found)
sourcebook watch	Auto-regenerate context files on source changes
sourcebook ask <query>	Query codebase knowledge in natural language

How It Works

Layer A — Rules-based (no LLM, <1 second)

1. Co-change analysis — mines git history for files that change together. If you touched auth.ts and it changes with session.ts in 88% of commits, sourcebook flags session.ts.
2. Test file detection — maps source files to test files via naming conventions and co-change history.
3. Import graph — builds a dependency graph and checks whether files that import (or are imported by) your changed files also need updates.
4. Hub detection — flags when you've modified a file with high fan-in (many dependents). These changes have blast radius.

Layer B — AI-powered (~$0.012/run)

Sends the diff plus dependency context to Claude Sonnet. Catches semantic relationships Layer A can't see — field renames that need migrations, validation logic that assumes old schemas, cross-module dependencies with no import link.

Every AI suggestion requires a dependency citation. Hallucinated file paths are filtered out. The completeness gate ensures zero false positives: if the diff is actually complete, Layer B stays silent.

Configuration

# Required for --ai flag only
export ANTHROPIC_API_KEY=sk-ant-...

No other configuration needed. sourcebook reads your repo's git history and file structure directly.

Language Support

Language	Import Graph	Git Analysis	Convention Detection
TypeScript / JavaScript	Full	Full	Full
Python	Full	Full	Full
Go	Full	Full	Full
Rust	Full	Full	Partial

Research

Built on real benchmarks, not vibes:

• Check validation results — methodology and accuracy data
• Benchmark: 19 tasks, 10 repos, 4 languages — controlled agent performance testing
• Why auto-generated context makes agents worse — the ETH Zurich finding that shaped our approach

License

BSL-1.1 — source-available, free to use, cannot be offered as a hosted service. Converts to MIT on 2030-03-25. See LICENSE for details.

---

sourcebook.run · GitHub · npm · @maroond_