{"id":49826936,"url":"https://github.com/maroondlabs/sourcebook","last_synced_at":"2026-05-29T09:00:27.575Z","repository":{"id":346706967,"uuid":"1191237951","full_name":"maroondlabs/sourcebook","owner":"maroondlabs","description":"Generate AI context files from your codebase's actual conventions. Not what agents already know — what they keep missing.","archived":false,"fork":false,"pushed_at":"2026-04-10T19:02:19.000Z","size":7934,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T20:27:41.098Z","etag":null,"topics":["agents-md","ai-coding","ai-context","claude-code","claude-md","codebase-context","cursor-rules","mcp-server","model-context-protocol","typescript"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maroondlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-25T03:37:36.000Z","updated_at":"2026-04-10T18:59:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maroondlabs/sourcebook","commit_stats":null,"previous_names":["maroondlabs/sourcebook"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/maroondlabs/sourcebook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maroondlabs%2Fsourcebook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maroondlabs%2Fsourcebook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maroondlabs%2Fsourcebook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maroondlabs%2Fsourcebook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maroondlabs","download_url":"https://codeload.github.com/maroondlabs/sourcebook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maroondlabs%2Fsourcebook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33644313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai-coding","ai-context","claude-code","claude-md","codebase-context","cursor-rules","mcp-server","model-context-protocol","typescript"],"created_at":"2026-05-13T18:00:29.031Z","updated_at":"2026-05-29T09:00:27.551Z","avatar_url":"https://github.com/maroondlabs.png","language":"HTML","funding_links":[],"categories":["Web-Based Tools","🔧 Tools \u0026 Ecosystem"],"sub_categories":["Codebase Intelligence","🔄 Project Handoffs"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"sourcebook\" width=\"120\" /\u003e\n\u003c/p\u003e\n\n# sourcebook\n\n**Catches the files your AI agent forgot to change.**\n\nA 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.\n\n```bash\nnpx sourcebook init          # sets up Claude Code hooks + generates CLAUDE.md\nnpx sourcebook check         # check your current diff for missing files\nnpx sourcebook scan-history  # see what you've been missing\n```\n\n## What It Catches\n\nYour AI agent changed the handler. Did it update the test? The sibling module? The config that references the old value?\n\nsourcebook checks your diff against the repo's actual structure:\n\n- **Missing test files** — source file changed, test file didn't\n- **Sibling modules** — files that import or are imported by what you changed\n- **Co-change companions** — files that historically change together in git commits\n- **Hub file blast radius** — you touched something with 50+ dependents\n\nWith `--ai`: cross-module semantic relationships, field renames that need migrations, stale validation logic.\n\n## Key Stats\n\n| Metric | Result |\n|--------|--------|\n| Completeness gate | 100% accurate (30/30 diffs) |\n| False positive rate | 0% on clean diffs |\n| Test file detection | 73% |\n| Sibling detection | 71% |\n| AI analysis cost | ~$0.012/run |\n\n## Four Surfaces\n\n### 1. CLI\n\nRun it on any diff. No setup required.\n\n```bash\nnpx sourcebook check              # check staged/unstaged changes\nnpx sourcebook check --ai         # add AI semantic analysis (requires ANTHROPIC_API_KEY)\nnpx sourcebook check --quiet      # exit code only (for CI/scripts)\nnpx sourcebook check --branch main  # compare vs a branch\n```\n\n### 2. Claude Code Hooks\n\nOne command wires up pre-commit hooks. Agent edits a file, sourcebook checks the diff, agent sees what's missing — all before the commit lands.\n\n```bash\nnpx sourcebook init   # generates CLAUDE.md + installs hooks\n```\n\n### 3. MCP Server\n\nPublished on the official MCP registry. Agents can query repo structure, blast radius, conventions, and co-change data on demand.\n\n```bash\nnpx sourcebook serve\n```\n\nAdd to your MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"sourcebook\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"sourcebook\", \"serve\", \"--dir\", \"/path/to/your/project\"]\n    }\n  }\n}\n```\n\n### 4. GitHub App (coming soon)\n\nAutomated completeness checks on every pull request. [Join the waitlist](https://sourcebook.run/teams).\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `sourcebook check` | Analyze current diff for completeness |\n| `sourcebook check --ai` | Add AI-powered semantic analysis (requires ANTHROPIC_API_KEY) |\n| `sourcebook check --quiet` | Exit code only — 1 if findings, 0 if clean |\n| `sourcebook check --json` | Structured JSON output |\n| `sourcebook check --branch main` | Compare HEAD against a branch |\n| `sourcebook check --threshold 0.9` | Custom co-change coupling threshold (0-1) |\n| `sourcebook init` | Set up Claude Code hooks + generate CLAUDE.md/AGENTS.md |\n| `sourcebook scan-history` | Retrospective scan of recent commits |\n| `sourcebook hooks` | Install or check Claude Code hooks |\n| `sourcebook truth` | Generate a Repo Truth Map (2.5D visualization) |\n| `sourcebook serve` | Start MCP server |\n| `sourcebook update` | Re-analyze while preserving manual edits |\n| `sourcebook diff` | Show what would change (exit code 1 if changes found) |\n| `sourcebook watch` | Auto-regenerate context files on source changes |\n| `sourcebook ask \u003cquery\u003e` | Query codebase knowledge in natural language |\n\n## How It Works\n\n### Layer A — Rules-based (no LLM, \u003c1 second)\n\n1. **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`.\n2. **Test file detection** — maps source files to test files via naming conventions and co-change history.\n3. **Import graph** — builds a dependency graph and checks whether files that import (or are imported by) your changed files also need updates.\n4. **Hub detection** — flags when you've modified a file with high fan-in (many dependents). These changes have blast radius.\n\n### Layer B — AI-powered (~$0.012/run)\n\nSends 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.\n\nEvery 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.\n\n## Configuration\n\n```bash\n# Required for --ai flag only\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\nNo other configuration needed. sourcebook reads your repo's git history and file structure directly.\n\n## Language Support\n\n| Language | Import Graph | Git Analysis | Convention Detection |\n|----------|:---:|:---:|:---:|\n| TypeScript / JavaScript | Full | Full | Full |\n| Python | Full | Full | Full |\n| Go | Full | Full | Full |\n| Rust | Full | Full | Partial |\n\n## Research\n\nBuilt on real benchmarks, not vibes:\n\n- [Check validation results](https://sourcebook.run/research/check-validation) — methodology and accuracy data\n- [Benchmark: 19 tasks, 10 repos, 4 languages](https://sourcebook.run/blog/19-tasks-10-repos-4-languages) — controlled agent performance testing\n- [Why auto-generated context makes agents worse](https://sourcebook.run/blog/why-auto-generated-context-makes-agents-worse) — the ETH Zurich finding that shaped our approach\n\n## License\n\nBSL-1.1 — source-available, free to use, cannot be offered as a hosted service. Converts to MIT on 2030-03-25. See [LICENSE](./LICENSE) for details.\n\n---\n\n[sourcebook.run](https://sourcebook.run) · [GitHub](https://github.com/maroondlabs/sourcebook) · [npm](https://www.npmjs.com/package/sourcebook) · [@maroond_](https://x.com/maroond_)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaroondlabs%2Fsourcebook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaroondlabs%2Fsourcebook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaroondlabs%2Fsourcebook/lists"}