sourcebook

KI kann deinen Code lesen. Sie weiß trotzdem nicht, wie dein Projekt funktioniert.

sourcebook erfasst das Projektwissen, das dein Team im Kopf hat — Konventionen, Muster, Fallen und wo Dinge tatsächlich hingehören — und verwandelt es in Kontext, den dein Coding-Agent nutzen kann.

npx sourcebook init

Tools wie Repomix geben der KI deine gesamte Codebasis. sourcebook gibt ihr dein Projektwissen.

Warum

KI-Coding-Agenten verbringen den Großteil ihres Kontextfensters mit Orientierung — sie lesen Dateien, um ein mentales Modell aufzubauen, bevor sie echte Arbeit leisten. Die meisten Kontextdateien (CLAUDE.md, .cursorrules) sind generisch und veralten schnell.

Untersuchungen zeigen, dass automatisch generierter Kontext, der offensichtliche Informationen wiederholt, die Leistung von Agenten tatsächlich um 2-3 % verschlechtert. Der einzige Kontext, der hilft, sind nicht direkt erkennbare Informationen — das Projektwissen, das Agenten nicht allein durch das Lesen des Codes herausfinden können.

sourcebook extrahiert nur das, was Agenten ständig übersehen: die Konventionen, versteckten Abhängigkeiten, fragilen Bereiche und dominanten Muster, die in den Köpfen deines Teams leben — nicht im Code.

Was es findet

• Import-Graph + PageRank — bewertet Dateien nach struktureller Wichtigkeit, identifiziert Hub-Dateien mit dem größten Blast-Radius

• Git-Historien-Forensik — rückgängig gemachte Commits („das nicht tun“-Signale), Co-Change-Kopplung (unsichtbare Abhängigkeiten), schnelle Nachbesserungen (Code, der schwer korrekt umzusetzen war), Anti-Patterns aus verworfenen Ansätzen

• Konventionserkennung — Namensmuster, Export-Stil, Import-Organisation, Barrel-Exporte, Pfad-Aliase, Verwendung von Typ-Hinweisen, Fehlerbehandlungsstil

• Framework-Erkennung — Next.js, Expo, Supabase, Tailwind, Express, TypeScript, Django, FastAPI, Flask, Go (Gin, Echo, Fiber)

• Kontext-Rot-bewusste Formatierung — kritische Einschränkungen oben, Referenzinformationen in der Mitte, Aktions-Prompts unten (optimiert für die Aufmerksamkeitsmuster von LLMs)

• Intelligente Budget-Durchsetzung — wenn der Kontext dein Token-Budget überschreitet, werden zuerst Abschnitte mit niedriger Priorität entfernt (kritische Einschränkungen bleiben immer erhalten)

Schnellstart

# Generate CLAUDE.md + AGENTS.md for your project
npx sourcebook init

# Generate for a specific tool
npx sourcebook init --format claude,agents  # CLAUDE.md + AGENTS.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 agents         # AGENTS.md only
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

Befehle

Optionen

Sprachunterstützung

GitHub Action

Kontextdateien bei jedem Merge automatisch aktualisieren:

# .github/workflows/sourcebook.yml
name: Update context files
on:
  push:
    branches: [main]

jobs:
  sourcebook:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: maroondlabs/sourcebook@main
        with:
          format: all

Beispielausgabe

Ausgeführt auf cal.com (10.456 Dateien):

sourcebook
Extracting repo truths...

✓ Scanned project structure
  10,456 files, 3 frameworks detected
✓ Extracted 11 findings

  ● Core modules: types.ts imported by 183 files — widest blast radius
  ● Circular deps: bookingScenario.ts ↔ getMockRequestData.ts
  ● Co-change: auth/provider.ts ↔ middleware/session.ts (88% correlation)
  ● Dead code: 1,907 orphan files detected
  ● Conventions: named exports preferred (26:2 ratio)
  ● Barrel exports: 40 index.ts re-export files
  ● Commit style: Conventional Commits (feat/fix/docs)

✓ Wrote CLAUDE.md
✓ Wrote AGENTS.md

Funktionsweise

sourcebook führt fünf Analysedurchläufe durch, alle deterministisch und lokal — keine KI, keine API-Schlüssel, keine Netzwerkaufrufe:

1. Statische Analyse — Framework-Erkennung, Build-Befehle, Projektstruktur, Umgebungsvariablen

2. Import-Graph — erstellt einen gerichteten Graphen aller Importe, führt PageRank aus, um die strukturell wichtigsten Dateien zu finden

3. Git-Forensik — durchsucht die Commit-Historie nach Reverts, Anti-Patterns, Co-Change-Kopplung, Churn-Hotspots und verworfenen Ansätzen

4. Konventions-Inferenz — stichprobenartige Untersuchung von Quelldateien zur Erkennung von Namens-, Import-, Export-, Fehlerbehandlungs- und Typ-Annotierungsmustern

5. Budget-Durchsetzung — wenn die Ausgabe das Token-Budget überschreitet, werden intelligent Abschnitte mit niedriger Priorität entfernt (zuerst ergänzende Erkenntnisse, niemals kritische Einschränkungen)

Anschließend wird ein Erkennbarkeitsfilter angewendet: Bei jeder Erkenntnis wird gefragt: „Kann ein Agent das durch Lesen des Codes herausfinden?“ Wenn ja, wird sie verworfen. Nur nicht direkt erkennbare Informationen gelangen in die Ausgabe.

Die Ausgabe ist für Kontext-Rot-Resistenz formatiert — kritische Einschränkungen stehen am Anfang und Ende der Datei (wo LLMs die meiste Aufmerksamkeit schenken), leichtgewichtige Referenzinformationen stehen in der Mitte.

MCP-Server

sourcebook serve startet einen lokalen MCP-Server (Model Context Protocol), der Live-Codebasis-Intelligenz für jeden MCP-kompatiblen KI-Client bereitstellt — Claude Desktop, Cursor und andere.

Anstatt einer statischen Kontextdatei kann dein KI-Agent die Architektur deines Projekts bei Bedarf abfragen: Blast-Radius vor dem Bearbeiten prüfen, Konventionen vor dem Schreiben von Code abgleichen, Git-Historie nach Anti-Patterns durchsuchen.

Installation

Füge sourcebook zu deiner MCP-Client-Konfiguration hinzu:

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

Claude Code — führe dies in deinem Terminal aus:

claude mcp add sourcebook -- npx -y sourcebook serve --dir /path/to/your/project

Oder füge es manuell zu ~/.claude/claude_desktop_config.json hinzu.

Claude Desktop — füge es zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu.

Cursor — füge es zu .cursor/mcp.json in deinem Projekt oder global zu ~/.cursor/mcp.json hinzu.

Andere MCP-Clients — jeder Client, der den STDIO-Transport unterstützt, funktioniert mit demselben Konfigurationsblock wie oben.

Starte deinen Client nach dem Aktualisieren der Konfiguration neu.

Verfügbare Tools

Der Server speichert den Scan im Arbeitsspeicher — nachfolgende Tool-Aufrufe sind schnell. Übergebe refresh: true an analyze_codebase, um einen erneuten Scan zu erzwingen.

Roadmap

• [x] .cursor/rules/sourcebook.mdc + Legacy .cursorrules Ausgabe

• [x] .github/copilot-instructions.md Ausgabe

• [x] sourcebook update — erneute Analyse unter Beibehaltung manueller Änderungen

• [x] sourcebook diff — zeigen, was sich geändert hat (CI-freundliche Exit-Codes)

• [x] --budget <tokens> — intelligente, PageRank-basierte Priorisierung

• [x] Anti-Pattern-Erkennung aus rückgängig gemachten Commits und gelöschten Dateien

• [x] Python-Unterstützung (Django, FastAPI, Flask, pytest)

• [x] Go-Unterstützung (Gin, Echo, Fiber, Modul-Layout)

• [x] GitHub Action für CI

• [x] sourcebook serve — MCP-Server-Modus

• [ ] Framework-Wissenspakete (von der Community beigesteuert)

• [ ] Tree-sitter AST-Parsing für tiefere Konventionserkennung

• [ ] Gehostetes Dashboard mit Kontext-Qualitäts-Scores

Forschungsgrundlage

Aufgebaut auf Erkenntnissen aus:

• ETH Zürich AGENTS.md Studie — automatisch generierter, offensichtlicher Kontext verschlechtert die Agentenleistung

• Karpathys autoresearch — kuratierter Kontext (program.md) ist der wichtigste Hebel für die Effektivität von Agenten

• Aiders repo-map — PageRank auf Import-Graphen für strukturelle Wichtigkeit

• Chromas Kontext-Rot-Forschung — LLMs zeigen 30%+ Genauigkeitsverlust bei Informationen in der Mitte des Kontexts

Lizenz

BSL-1.1 — Source-Available, kostenlos nutzbar, darf nicht als gehosteter Dienst angeboten werden. Wandelt sich am 25.03.2030 in MIT um. Siehe LICENSE für Details.