🧠 ProjectBrain

Codebase Intelligence, Architecture Guardrails & AI Context Engineering for VS Code.
Understand the codebase before the AI changes it • Zero-Cloud by Default • AST & Graph First

English • Русский • 简体中文 • 日本語 • Português • Español • 한국어 • Deutsch • Français • Українська

---

🌟 Why ProjectBrain?

In modern AI-assisted development ("vibe coding"), LLM agents quickly generate code, but also introduce hidden architecture rot, duplicate utilities, broken type references, and hallucinated context.

ProjectBrain transforms chaotic AI-generated codebases into a structured, verifiable workspace. It is not another autonomous code generator — it is your codebase's Observer, Analyzer, Guard, and Context Builder.

$$\text{Static Analysis (AST/Graph)} \longrightarrow \text{Templates} \longrightarrow \text{Local LLM (Ollama/HF)} \longrightarrow \text{Cloud LLM (Optional)}$$

---

⚡ Key Highlights

• 🔍 Dead Code & Zombie Symbol Hunter: Recursively analyzes call trees and incoming reference graphs to identify dead files, unused exports, zombie functions, and orphaned API routes.
• 👥 Semantic & Structural Duplicate Detection: 4-tier comparison (Exact AST → Control Flow Graph → Normalized Syntax → Local Vector/LLM Reasoning) prevents AI agents from reinventing existing functions.
• 🗺️ Full Architecture Flow Discovery: Automatically traces end-to-end pathways: $$\text{Route} \longrightarrow \text{Handler} \longrightarrow \text{Service} \longrightarrow \text{Repository} \longrightarrow \text{Model} \longrightarrow \text{Database Table}$$
• 🎯 AI Context Engineering & Task Boundaries: Generates pinpoint .projectbrain/projectbrain-prompt.md context packets with explicit DO NOT DUPLICATE guardrails and resets stale context between task sessions.
• 🛡️ AI Change Review & Snapshots: Compares codebase snapshots before and after AI agent execution, catching new type errors, convention breaches, and leaked secrets.
• 🔒 Zero-Cloud Privacy by Default: All indexation and graph databases run locally in embedded SQLite (.projectbrain/). Zero telemetry, zero unauthorized external network calls.

---

🏛️ Monorepo Architecture

ProjectBrain is engineered with a modular, decoupled architecture powered by Bun Workspaces:

projectbrain/
├── apps/
│   ├── vscode/               # @projectbrain/vscode (VS Code Extension VSIX)
│   └── cli/                  # @projectbrain/cli (Standalone CLI — Planned)
│
├── packages/
│   ├── shared/               # Domain models, AST & Graph interfaces, DTOs
│   ├── parser/               # Multi-language AST parser registry (TS, JS, SCSS, JSON, YAML)
│   ├── indexer/              # High-speed workspace crawler & symbol indexer
│   ├── graph/                # Bidirectional dependency & architecture flow graph
│   ├── analyzer/             # Dead code engine, duplicate detector, compiler health
│   ├── rules/                # Declarative YAML project convention rule engine
│   ├── templates/            # Weighted heuristic composition & template matcher
│   ├── security/             # Secret scanner, credentials detector & git guardrails
│   ├── git/                  # Repository history, diff & branch analyzer
│   ├── ai/                   # AI Router, Relevance scoring, Prompt builder
│   └── core/                 # Central orchestrator & local SQLite storage manager
│
└── template-pack/            # Built-in framework & architectural heuristic templates

---

🚀 Quick Start

Prerequisites

• Bun v1.4.0+
• VS Code v1.90.0+

1. Clone & Install

git clone https://github.com/oneheka/Project-Brain-AI.git
cd Project-Brain-AI
bun install

2. Typecheck & Build

# Run typecheck across all workspace packages
bun run typecheck

# Compile VS Code extension
bun run compile:vscode

3. Launch in VS Code

Open the project in VS Code, navigate to the Run & Debug panel (F5), and select "Launch Extension" to spin up an Extension Development Host.

---

🔒 Strict Security Guardrails

• Zero Leaks: Secrets, private keys (.pem), connection strings, and .env files are strictly ignored by .gitignore.
• Safe Configuration: Use .env.example as a reference when configuring optional local LLM providers (e.g. Ollama).
• Git Guardrails: The security scanner inspects staged changes and commit history to ensure no sensitive credentials are ever committed.

---

📄 License

Distributed under the MIT License. Developed with ❤️ by oneheka.