sourcebook
AI can read your code. It still doesn't know how your project works.
sourcebook captures the project knowledge your team carries in its head — conventions, patterns, traps, and where things actually go — and turns it into context your coding agent can use.
npx sourcebook init
Tools like Repomix give AI your entire codebase. sourcebook gives it your project knowledge.
Why
AI coding agents spend most of their context window orienting — reading files to build a mental model before doing real work. Most context files (CLAUDE.md, .cursorrules) are generic and go stale fast.
Research shows auto-generated context that restates obvious information actually makes agents worse by 2-3%. The only context that helps is non-discoverable information — the project knowledge agents can't figure out by reading code alone.
sourcebook extracts only what agents keep missing: the conventions, hidden dependencies, fragile areas, and dominant patterns that live in your team's heads — not in the code.
What It Finds
- Import graph + PageRank — ranks files by structural importance, identifies hub files with the widest blast radius
- Git history forensics — reverted commits ("don't do this" signals), co-change coupling (invisible dependencies), rapid re-edits (code that was hard to get right), anti-patterns from abandoned approaches
- Convention detection — naming patterns, export style, import organization, barrel exports, path aliases, type hint usage, error handling style
- Framework detection — Next.js, Expo, Supabase, Tailwind, Express, TypeScript, Django, FastAPI, Flask, Go (Gin, Echo, Fiber)
- Context-rot-aware formatting — critical constraints at the top, reference info in the middle, action prompts at the bottom (optimized for LLM attention patterns)
- Smart budget enforcement — when context exceeds your token budget, drops low-priority sections first (keeps critical constraints always)
Quick Start
# Generate CLAUDE.md for your project
npx sourcebook init
# Generate for a specific tool
npx sourcebook init --format claude # CLAUDE.md (default)
npx sourcebook init --format cursor # .cursor/rules/sourcebook.mdc + .cursorrules
npx sourcebook init --format copilot # .github/copilot-instructions.md
npx sourcebook init --format all # All of the above
# Re-analyze while preserving your manual edits
npx sourcebook update
# See what changed since last generation (exit code 1 = changes found)
npx sourcebook diff
# Limit output to a token budget (drops low-priority sections first)
npx sourcebook init --budget 1000
Commands
| Command | What it does |
|---------|-------------|
| sourcebook init | Analyze codebase and generate context files |
| sourcebook update | Re-analyze while preserving sections you added manually |
| sourcebook diff | Show what would change without writing files (exit code 1 if changes found — useful for CI) |
| sourcebook serve | Start an MCP server exposing live codebase intelligence |
Options
| Flag | Description | Default |
|------|-------------|---------|
| -d, --dir <path> | Target directory | . |
| -f, --format <formats> | Output formats: claude, cursor, copilot, all | claude |
| --budget <tokens> | Max token budget for output | 4000 |
| --dry-run | Preview findings without writing files | — |
Language Support
| Language | Framework Detection | Convention Detection | Import Graph | Git Analysis |
|----------|:------------------:|:-------------------:|:------------:|:------------:|
| TypeScript/JavaScript | Next.js, Expo, Vite, React, Express, Tailwind, Supabase | Barrel exports, path aliases, export style, error handling | Full | Full |
| Python | Django, FastAPI, Flask, pytest
... View full README on GitHub
