Code Project Brain (CPB)

Ein projektweites Second Brain, das synchron mit einem Code-Repository wächst. Ein Entwicklungsleitfaden (Kontext erster Klasse) liegt über CodeGraph (Fakten) und Project KB (aufbereitetes Wissen), kompiliert zu aufgabenspezifischem Kontext für Claude Code – mit einem geregelten Änderung → Vorschlag-Loop, der Wissen korrekt hält, ohne dass eine KI es jemals stillschweigend umschreibt.

CPB implementiert das v3.0-Design: Der Entwicklungs- leitfaden ist der erste Bürger – das mentale Projektmodell, das ein Agent zuerst lädt. Ein Context Compiler erstellt einen ContextPlan in der festen Reihenfolge Leitfaden → KB → CodeGraph; ein Concept-Hub verbindet die drei Domänen über canonical_id; eine Code-Anker-Schicht hält den Leitfaden gegenüber dem Code ehrlich.

Development Guide (context / first-class)
        │  describes / governs (via Concept hub)
        ▼
CodeGraph (facts)  ·  Project KB (digested knowledge)
        └──────────────► Context Compiler ► Claude Code
Change → Impact → (Guide stale?) → Guide Proposal → Validate → Approve → Apply

Neu hier? Lies docs/OVERVIEW.md – eine Einzel-Einstiegs- Tour durch Architektur, Implementierung, Designentscheidungen und Roadmap. Die v2.0-Historie liegt in UpdateGuide2.0.md.

Die drei Ebenen (v3.0, update3.0 §1)

Die feste Ladereihenfolge ist Leitfaden → KB → CodeGraph, niemals umgekehrt (§3):

• Entwicklungsleitfaden = Kontext – was das Projekt ist, warum es so gestaltet ist und welche Regeln zu befolgen sind. Das mentale Modell, das ein Agent zuerst lädt. Liegt in guide/ als Skelett 00-overview → 06-decisions (§14).

• CodeGraph = Fakten – Code, der von tree-sitter in einen SQLite-Graphen aus Symbolen und Call/Referenz-Kanten geparst wird (WAL + FTS5). Der Ground-Truth-Adapter, der die Code-Anker des Leitfadens verifiziert (§9). WAS IST.

• Project KB = Wissen – aufbereitete Anforderungen / Bugs / Entscheidungen (ADRs) / externe Quellen / Lektionen. Die detaillierte, historische Ebene, die erst nach dem Leitfaden erreicht wird. WAS GELERNT WURDE.

Der Concept-Hub (§21/§22) verbindet Leitfaden-Abschnitte, KB-Dokumente und CodeGraph- Symbole über canonical_id, sodass eine Codeänderung Symbol → Konzept → Leitfaden-Abschnitt nachverfolgen und den Leitfaden als veraltet markieren kann.

Der geregelte Loop (§11/§13/§24)

Eine Code- oder KB-Änderung bearbeitet den Leitfaden nie stillschweigend. Stattdessen:

Change → Impact → Concept impact → Guide stale? → Guide Proposal (draft)
      → Validate → Approve → Apply

Die Engine schlägt vor; ein Mensch (oder Claude als Prüfer) validiert und genehmigt vor der Anwendung. KB-Wissen kann durch denselben geregelten Vorschlag in den Leitfaden befördert werden (§13 Knowledge Promotion). cpb sync entwirft ausstehende Vorschläge; cpb proposals <id> --approve|… disponiert sie.

Was es tut

• Entwicklungsleitfaden – indiziert guide/-Markdown (Skelett-Frontmatter + Code-Anker), verifiziert Anker gegen CodeGraph, markiert veraltete.

• CodeGraph – pro-Datei inkrementelle Synchronisation von Symbolen + Kanten.

• Project KB – indiziert project-kb/-Markdown mit typisiertem Frontmatter; verdaut zu kb_digests; Dedup/Merge doppelter Digests (§13).

• Context Compiler – cpb context "<task>" → ein ContextPlan (Leitfaden → KB → Code, Progressive Disclosure Level 0-6, Token-budgetiert) (§18).

• Impact Engine – Blast-Radius + betroffene Constraints/Entscheidungen und betroffene Konzepte / Leitfaden-Abschnitte (§22).

• Concept-Hub – canonical_id, der Leitfaden / KB / CodeGraph verbindet (§21).

• Claude Code Skills – acht Workflows: /project-init, /project-context, /project-feature, /project-impact, /project-update-docs, /project-review, /project-knowledge, /project-sync.

Technik

Node/TypeScript, node:sqlite (eingebaut, WAL+FTS5, Node ≥ 22), web-tree-sitter (WASM-Grammatiken für C/C++/TS/JS/Python/Rust/Go/Java). Keine nativen Builds, keine Vektor-DB (bewusst, §19). Engine v3.0.0 / Protokoll 2.

Schnellstart

# inside a code repository
cpb init        # create .project-brain/ + guide/ + project-kb/
cpb index       # build codegraph + knowledge + guide + concepts + git
cpb status      # summary: engine/protocol/guide sections/stale anchors
cpb context FrameQueue        # ContextPlan (Guide → KB → CodeGraph)
cpb concept camera/capture-pipeline   # the Concept hub: 3-domain graph
cpb guide list               # the Guide skeleton (Level 0)
cpb guide validate           # Guide well-formedness (§17 validator)
cpb impact FrameQueue         # blast radius + affected concepts/guide
cpb kb dedup                  # find duplicate KB digests (§13); --apply to merge
cpb sync                      # detect changes → draft Guide/Update proposals
cpb proposals                 # list / validate / approve / apply proposals

Selbst-Hosting

CPB indiziert seinen eigenen Quellcode und die enthaltenen guide/ + project-kb/:

git init && cpb init && cpb index && cpb status

MCP (die KI-Schnittstelle)

CPB stellt namespaced MCP-Tools bereit – die einzige KI-Schnittstelle:

• code.* – code.search code.symbol code.callers code.callees code.dependencies code.impact

• docs.* – docs.get docs.search docs.related docs.constraints docs.validate docs.apply

• kb.* – kb.search kb.requirement kb.bug kb.decision kb.reference kb.ingest kb.promote kb.digest kb.promote-guide kb.dedup

• guide.* – guide.index guide.section guide.stale guide.validate

• concept.* – concept.graph concept.forSymbol

• project.* – project.context project.impact project.changes project.sync project.proposals project.status

Siehe USAGE.md für die Installationskonfiguration und die vollständige Tool-Referenz.

Als Claude-Code-Plugin

CPB wird als Claude-Code-Plugin (cpb-claude-plugin/) ausgeliefert, das die Adapter- Schicht über der Engine ist. Die Engine (dieses Repo, cpb/cpb-mcp-CLI) bleibt eine eigenständige Laufzeit; das Plugin bindet über das MCP-Protokoll, nicht über einen npm-Import – damit sich die Engine unabhängig weiterentwickeln kann. Siehe docs/plans/archi.md für die Begründung und cpb-claude-plugin/README.md für vollständige Installationsschritte.

# 1. Engine on PATH (once)
npm install -g @cpb/engine        # or: npm link  (from this repo)

# 2. In Claude Code
/plugin marketplace add /path/to/CPB
/plugin install cpb@cpb

Dann /cpb:status, /cpb:context, /cpb:sync, … – oder einfach die Aufgabe beschreiben und die Skills aktivieren sich automatisch.

Das Demo-Projekt

demo-src/camera/ ist eine kleine C++-Kamera-Pipeline (CameraDevice → FrameQueue → VideoEncoder) mit einem vollständigen v3.0-Dokumentationssatz – guide/ (Überblick + Architektur + eine Constraint + ein ADR) und project-kb/ (ADR, Anforderung, Bug, Lektion, externe V4L2/FFmpeg-Notizen, Testnachweise). Es ist Dogfood: CPB indiziert, erkundet, prüft auf Drift und führt den Änderung→Vorschlag-Loop darauf aus.

Layout

src/
  core/        types (domain model: Guide/Concept/ContextPlan + structured objects)
  db/          sqlite adapter + schema.sql + migrate.ts (versioned migrations)
  engine/
    codegraph/  tree-sitter extractor, grammars, parser, orchestrator, queries
    guide/      Development Guide: indexer, anchor, query, validator (§17)
    concept/    Concept hub: index + query (§21)
    knowledge/  KB: frontmatter, indexer, recall, freshness, entities, external, ingestion, promotion, dedup
    docs/       structured reads: constraints, decisions (Guide-seeded)
    git/        commit index + ADR mining + gitDiff
    impact/     blast radius + affected knowledge/concepts/guide (§22)
    context/    Context Compiler (§18) + builder (v2, cpb explain) + explain/explore
    sync/       semantic-diff, changeset, proposal, pipeline (change→proposal loop)
  mcp/         namespaced MCP tools (code.*/docs.*/kb.*/guide.*/concept.*/project.*) + stdio server
bin/cpb.ts      CLI
guide/          CPB's own Development Guide (self-hosted, v3.0 skeleton)
cpb-claude-plugin/  the Claude Code adapter (skills + commands + MCP declaration)

Design-Grenzen (gemäß §19/§23/§25)

Nicht gebaut: automatisches Umschreiben aller Dokumente, automatisches Generieren allen Wissens, Vektor-/ Embedding-Suche (§19 – lokal-first, SQLite+FTS5), eine vollständige IDE oder ein Enterprise-Wissensgraph. Die Engine bettet nie ein LLM ein (§29) – Claude denkt über MCP; die Engine hält Fakten und die Zustandsmaschine. Wissen bleibt menschlich kontrolliert (§11/§14); der Leitfaden ist ein geregeltes Asset – jede Bearbeitung läuft über einen Vorschlag. Code ist die höchste Quelle der Wahrheit (§9).

Lizenz

MIT.