Code Project Brain (CPB)

A project-level second brain that grows in sync with a code repository. A Development Guide (first-class context) sits over CodeGraph (facts) and Project KB (digested knowledge), compiled into task-specific context for Claude Code — with a governed Change → Proposal loop that keeps knowledge correct without ever letting an AI silently rewrite it.

CPB implements the v3.0 design: the Development Guide is the first citizen — the project mental model an Agent loads first. A Context Compiler assembles a ContextPlan in the fixed order Guide → KB → CodeGraph; a Concept hub links the three domains by canonical_id; a Code Anchor layer keeps the Guide honest against the code.

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

New here? Read docs/OVERVIEW.md — a single-entry tour of the architecture, implementation, design choices, and roadmap. v2.0 history lives in UpdateGuide2.0.md.

The three layers (v3.0, update3.0 §1)

The fixed load order is Guide → KB → CodeGraph, never the reverse (§3):

• Development Guide = Context — what the project is, why it's designed this way, and the rules to follow. The mental model an Agent loads first. Sits in guide/ as a skeleton 00-overview → 06-decisions (§14).
• CodeGraph = Facts — code parsed by tree-sitter into a SQLite graph of symbols and call/reference edges (WAL + FTS5). The Ground Truth Adapter that verifies the Guide's Code Anchors (§9). WHAT IS.
• Project KB = Knowledge — digested requirements / bugs / decisions (ADRs) / external sources / lessons. The detailed, historical layer reached only after the Guide. WHAT WAS LEARNED.

The Concept hub (§21/§22) links Guide sections, KB docs, and CodeGraph symbols by canonical_id, so a code change can trace symbol → concept → guide section and flag the Guide stale.

The governed loop (§11/§13/§24)

A code or KB change never silently edits the Guide. Instead:

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

The engine proposes; a human (or Claude, as reviewer) validates and approves before apply. KB knowledge can be promoted into the Guide through the same governed proposal (§13 Knowledge Promotion). cpb sync drafts pending proposals; cpb proposals <id> --approve|… dispositions them.

What it does

• Development Guide — indexes guide/ Markdown (skeleton frontmatter + Code Anchors), verifies anchors against CodeGraph, flags stale ones.
• CodeGraph — per-file incremental sync of symbols + edges.
• Project KB — indexes project-kb/ Markdown with typed frontmatter; digests into kb_digests; dedup/merge of duplicate digests (§13).
• Context Compiler — cpb context "<task>" → a ContextPlan (Guide → KB → Code, Progressive Disclosure Level 0-6, token-budgeted) (§18).
• Impact Engine — blast radius + affected constraints/decisions and affected concepts / Guide sections (§22).
• Concept hub — canonical_id linking Guide / KB / CodeGraph (§21).
• Claude Code Skills — eight workflows: /project-init, /project-context, /project-feature, /project-impact, /project-update-docs, /project-review, /project-knowledge, /project-sync.

Tech

Node/TypeScript, node:sqlite (built-in, WAL+FTS5, Node ≥ 22), web-tree-sitter (WASM grammars for C/C++/TS/JS/Python/Rust/Go/Java). No native builds, no vector DB (by design, §19). Engine v3.0.0 / protocol 2.

Quick start

# 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

Self-host

CPB indexes its own source and the included guide/ + project-kb/:

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

MCP (the AI interface)

CPB exposes namespaced MCP tools — the sole AI interface:

• 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

See USAGE.md for the install config and full tool reference.

As a Claude Code Plugin

CPB ships as a Claude Code plugin (cpb-claude-plugin/) that is the adapter layer over the Engine. The Engine (this repo, cpb/cpb-mcp CLI) stays a standalone runtime; the plugin binds via the MCP protocol, not an npm import — so the Engine can evolve independently. See docs/plans/archi.md for the rationale and cpb-claude-plugin/README.md for full install steps.

# 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

Then /cpb:status, /cpb:context, /cpb:sync, … — or just describe the task and the skills auto-activate.

The demo project

demo-src/camera/ is a small C++ camera pipeline (CameraDevice → FrameQueue → VideoEncoder) with a full v3.0 doc set — guide/ (overview + architecture + a constraint + an ADR) and project-kb/ (ADR, requirement, bug, lesson, external V4L2/FFmpeg notes, test evidence). It is dogfood: CPB indexes, explores, drift-checks, and runs the change→proposal loop on it.

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 boundaries (per §19/§23/§25)

Not built: auto-rewriting all docs, auto-generating all knowledge, vector/ embedding search (§19 — local-first, SQLite+FTS5), a full IDE, or an enterprise knowledge graph. The engine never embeds an LLM (§29) — Claude thinks via MCP; the engine holds facts and the state machine. Knowledge stays human-controlled (§11/§14); the Guide is a governed asset — every edit goes through a Proposal. Code is the highest source of truth (§9).

License

MIT.