sourcebook — Summary

sourcebook is an npm CLI tool and MCP server that generates AI context files (CLAUDE.md, AGENTS.md, Cursor rules) from a codebase's actual git history and import graph — capturing conventions, constraints, and hidden couplings that agents consistently miss. It operates in two layers: Layer A (rules-based, <1 second, zero cost) mines git co-change history and static import graphs to identify test file mappings, sibling modules, and hub files with high fan-in; Layer B (AI-powered, ~$0.012/run) uses Claude Sonnet to catch semantic cross-module dependencies invisible to static analysis. The sourcebook check command flags files that should have been changed alongside a given diff — a completeness gate for AI agent edits. With 3 stars, BSL-1.1 license (converts to MIT in 2030), and research-backed accuracy claims (0% false positives on clean diffs), it is the most rigorous "context quality" tool in the corpus.

Compared to seeds: no seed generates CLAUDE.md from codebase analysis. The closest seed is agent-os (which ships conventions as pre-written markdown) but agent-os's content is generic templates; sourcebook generates project-specific content from actual git history. The sourcebook check completeness gate is architecturally similar to spec-kit's PostToolUse hooks that run tests after edits, but applied to change completeness rather than test passage.

sourcebook — Overview

Origin

Created by maroondlabs (GitHub). May 2026 active development, v0.14.0. Published on npm as sourcebook. BSL-1.1 licensed (source-available, converts to MIT on 2030-03-25). Available on the official MCP registry.

Philosophy

From README:

"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."

Research foundation:

• ETH Zurich finding: "auto-generated obvious context hurts agent performance by 2-3%"
• Chroma Research: "30%+ accuracy drop for info in the middle of context"

Design implication: sourcebook generates ONLY non-discoverable information. Standard patterns (test frameworks, obvious directories) are stripped unless --verbose is passed.

Generator Output Philosophy

From source code comment:

/**
 * Design principles (from research):
 * 1. ONLY non-discoverable information (ETH Zurich: auto-generated obvious context hurts by 2-3%)
 * 2. Context-rot-aware formatting (Chroma Research: 30%+ accuracy drop for info in the middle)
 *    → Critical info at BEGINNING and END of file
 * 3. Karpathy's program.md pattern: constraints, gotchas, and autonomy boundaries
 */

Key Stats

sourcebook — Architecture

Distribution

• Type: npm-package + MCP server
• Binary: sourcebook
• Version: 0.14.0
• Install: npx sourcebook init (zero global install required)

Runtime Requirements

• Node.js
• Git (for co-change analysis)
• ANTHROPIC_API_KEY (optional, for --ai flag)

Layer Architecture

Layer A — Rules-based (no LLM, <1 second)
├── Co-change analysis (git history mining)
│   └── Files that change together >= threshold times
├── Test file detection (naming conventions + co-change)
├── Import graph (dependency graph via static analysis)
│   └── PageRank for hub file importance ranking
└── Hub detection (files with 50+ dependents)

Layer B — AI-powered (~$0.012/run)
└── Claude Sonnet semantic analysis
    ├── Cross-module semantic relationships
    ├── Field renames requiring migrations
    └── Stale validation logic
    ✓ Requires dependency citation — no hallucinated paths
    ✓ Completeness gate: silent if diff is actually clean

Source Structure

src/
├── cli.ts             # Entry point
├── commands/
│   ├── check.ts       # Completeness analysis
│   ├── init.ts        # Claude Code hooks + CLAUDE.md
│   ├── ask.ts         # NL query
│   ├── serve.ts       # MCP server
│   ├── truth.ts       # Repo Truth Map
│   ├── watch.ts       # Auto-regenerate on changes
│   └── ...
├── scanner/
│   ├── index.ts       # Two-pass scanner (structural first, git second)
│   ├── graph.ts       # Import graph + PageRank
│   └── git.ts         # Co-change analysis
└── generators/
    ├── claude.ts      # CLAUDE.md generator
    ├── agents.ts      # AGENTS.md generator
    ├── cursor.ts      # Cursor rules generator
    └── truth.ts       # 2.5D visualization

Language Support

sourcebook — Components

CLI Binary: sourcebook

MCP Server

• sourcebook serve starts the MCP server
• Published on official MCP registry
• Tools exposed:
  • get_blast_radius — what breaks if you edit a hub file
  • query_conventions — confirm the right pattern before adding code
  • get_pressing_questions — briefing before editing an unfamiliar file
  • get_co_change_pairs — files that historically change together

Generators (4)

Claude Code Hooks (installed by sourcebook init)

• PostToolUse hook that triggers completeness check after file edits
• Writes findings to context before the agent proceeds

sourcebook — Uniqueness

differs_from_seeds

No seed generates AI context files from codebase analysis. Every seed uses human-authored templates (agent-os, claude-conductor), framework-specific schema files (openspec, spec-kit), or no context injection at all (ccmemory). sourcebook inverts the pattern: it mines the codebase's actual git history and import graph to discover project-specific conventions and constraints, then generates a CLAUDE.md encoding those discoveries. The closest seed is agent-os (which ships CLAUDE.md-style templates) but agent-os content is generic; sourcebook content is project-specific and machine-generated. The completeness gate (sourcebook check) is architecturally similar to spec-kit's PostToolUse hooks (which run tests after edits), but checks change completeness (missing sibling files) rather than code correctness. The research-backed CLAUDE.md generation design — placing critical constraints at beginning and end, stripping discoverable context — is unique in the corpus.

Positioning

A "meta-tool" for AI agents — it doesn't guide how agents write code, it ensures agents have accurate project context before writing. Where other frameworks tell agents how to work (process, workflow, phases), sourcebook tells agents what to know (hidden couplings, hub files, deprecated patterns). The tool also actively guards against over-contextualization (the ETH Zurich finding that verbose auto-generated context hurts performance).

Observable Failure Modes

1. Context staleness: CLAUDE.md is a snapshot of the codebase at generation time. In fast-moving projects, it can go stale within days. sourcebook watch mitigates but adds process overhead.
2. False negative risk: Layer A catches 73% of test file needs and 71% of siblings — the 27-29% miss rate means agents may miss some updates even with sourcebook running.
3. AI layer cost accumulation: at $0.012/run, frequent usage in CI across a large team can add up. The --quiet flag without --ai avoids this but loses semantic analysis.
4. BSL-1.1 license: cannot be offered as a hosted service. Teams wanting a hosted version must wait until 2030 or use the planned GitHub App (waitlist).
5. No spec layer: sourcebook describes existing code conventions but doesn't help plan new features. It's a context quality tool, not a planning framework.