ProjectBrain (projectbrain-mcp)

Local-first AST Context Compiler, Closed-World Dossier, and Surgical Anchor Patch Engine for AI Coding Agents.

ProjectBrain indexes your codebase into a typed AST & call-graph (file, fn, cls, route, mod) in ~90ms and cuts coding-agent token bills by 60%–65% while speeding up multi-file debugging by 30%–42%:

• Input Token Reduction (-81.3% to -88.3% code tokens, -73.2% to -76.3% billed prompt tokens): Compiles module constants, smart-folded AST function slices, 1–3 hop bidirectional call chains with @L<line> caller windows, and a Closed-World Exhaustive Repo Scan into a single <800-line .projectbrain_dossier.md read in 1 read_file call.
• Output Token Reduction (-63.2% to -77.3% edit output tokens): Replaces verbatim Target + Replacement repetition (edit_file) with a compact Anchor Patch DSL (@file, @sub, @replace, @insert_after, @delete) validated by Tree-sitter in <5ms.
• Live ROI & Savings Ledger (projectbrain stats): Tracks cumulative input/output tokens saved, file reads avoided, estimated USD saved, and developer wait-time saved in .projectbrain_ledger.json.

Quick Start (60 Seconds)

pip install projectbrain-mcp
projectbrain --path /path/to/repo init

Or run as a zero-install MCP server via uvx:

{
  "mcpServers": {
    "projectbrain": {
      "command": "uvx",
      "args": ["projectbrain-mcp"]
    }
  }
}

projectbrain init indexes the repository, updates .gitignore, writes .mcp.json (for Claude Code, Cursor, Windsurf, Antigravity), and creates .agents/rules/projectbrain.md so agents automatically use brain_dossier and brain_patch.

Verified A/B Benchmark Results (142-File Production Repo)

CLI Reference

# 1. One-command repo initialization (index + .gitignore + .mcp.json + agent rules)
projectbrain --path <repo> init

# 2. Compile a single-read (<800-line) Engineering Dossier (.projectbrain_dossier.md)
projectbrain --path <repo> dossier "<question_or_bug_1>" "<question_or_bug_2>"

# 3. Apply or dry-run a Surgical Anchor Patch spec (.projectbrain_patch.diff)
projectbrain --path <repo> patch --spec "@file src/App.tsx
@sub L84 \`!profileCompleted\` -> \`isHydrated && !profileCompleted\`" [--apply]

# 4. View Live ROI & Token Savings Dashboard
projectbrain --path <repo> stats --summary

# 5. Additional granular tools
projectbrain --path <repo> slice --summary <file:symbol_or_start-end>
projectbrain --path <repo> compile "<task>" --summary
projectbrain --path <repo> explore <symbol_or_route> [target_b]
projectbrain --path <repo> impact <file1> [file2 ...]
projectbrain --path <repo> remember <symbol_or_file> "<architectural_note>"

MCP Server (projectbrain-mcp)

Exposes native MCP tools for Claude Code, Cursor, Windsurf, and Antigravity:

• brain_dossier(tasks, impact_files=None, repo_path=None) — Compiles <800-line .projectbrain_dossier.md with module globals, folded AST slices, call chains, and Closed-World Exhaustive Repo Scan.
• brain_patch(spec, apply=False, repo_path=None) — Executes or dry-runs Anchor Patch DSL (@file, @sub L<n>|*|ALL|<symbol>, @replace, @insert_after, @delete) with Tree-sitter syntax verification.
• brain_stats(repo_path=None, reset=False) — Returns cumulative token, dollar, and time savings from .projectbrain_ledger.json.
• brain_slice, brain_context, brain_explore, brain_check, brain_remember.