@theihtisham/agent-shadow-brain 1.1.1 → 2.1.0

package/README.md

@@ -1,237 +1,837 @@
-# Agent Shadow Brain
-
 <div align="center">
-  <img src="docs/images/banner.svg" alt="Agent Shadow Brain Banner" width="100%" />
-</div>
+
+<img src="banner.svg" alt="Agent Shadow Brain" width="100%">
 
 <br/>
 
-<div align="center">
+[![npm version](https://img.shields.io/npm/v/@theihtisham/agent-shadow-brain?color=a855f7&labelColor=1a0a2e&style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
+[![npm downloads](https://img.shields.io/npm/dt/@theihtisham/agent-shadow-brain?color=06b6d4&labelColor=1a0a2e&style=for-the-badge)](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
+[![license](https://img.shields.io/badge/license-MIT-8b5cf6?labelColor=1a0a2e&style=for-the-badge)](https://github.com/theihtisham/agent-shadow-brain/blob/master/LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?labelColor=1a0a2e&style=for-the-badge&logo=node.js)](https://nodejs.org/)
+[![GitHub stars](https://img.shields.io/github/stars/theihtisham/agent-shadow-brain?color=f59e0b&labelColor=1a0a2e&style=for-the-badge&logo=github)](https://github.com/theihtisham/agent-shadow-brain/stargazers)
+
+<br/>
 
-[![npm version](https://img.shields.io/npm/v/@theihtisham/agent-shadow-brain.svg)](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
-[![npm downloads](https://img.shields.io/npm/dm/@theihtisham/agent-shadow-brain.svg)](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
-[![license](https://img.shields.io/npm/l/@theihtisham/agent-shadow-brain.svg)](https://github.com/theihtisham/agent-shadow-brain/blob/main/LICENSE)
-[![node](https://img.shields.io/node/v/@theihtisham/agent-shadow-brain.svg)](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
+### **Mythos-Level Intelligence for AI Coding Agents**
 
-**A shadow AI brain that runs alongside your coding agent — watching, reviewing, and injecting intelligence in real-time.**
+No such brain and intelligence has existed before. Shadow Brain is a **super ultra intelligent** real-time intelligence layer powered by Claude Opus 4.6 (or latest model on any agentic AI) that watches your AI coding agents work, applies **mathematically rigorous algorithms** — Shannon entropy, Bayesian inference, cosine similarity, Tarjan's SCC — and injects expert insights back into their memory, making every agent write **better, safer, faster code** across sessions.
 
-Works with **Claude Code** · **Kilo Code** · **Cline** · **OpenCode** · **Codex CLI** · and more
+> **Quantum Neural Mesh** — Multiple Shadow Brain instances share knowledge in real-time. What one brain learns, all connected brains know instantly. Cross-session, cross-project, cross-agent superintelligence.
 
-[Quick Start](#install) · [How It Works](#how-it-works) · [CLI Reference](#cli-reference) · [Personalities](#brain-personalities) · [API](#programmatic-api)
+[**Getting Started**](#-getting-started) · [**Features**](#-features) · [**Neural Mesh**](#-quantum-neural-mesh) · [**CLI Reference**](#-cli-reference) · [**API**](#-programmatic-api) · [**Architecture**](#-architecture)
 
 </div>
 
 ---
 
-## Install
+## The Problem
+
+You use AI coding agents like Claude Code, Cline, Kilo Code, OpenCode, Codex, Roo Code, or Aider. They're powerful, but:
+
+- They **repeat the same mistakes** across sessions
+- They **don't learn** from your codebase patterns
+- They **miss security vulnerabilities** in generated code
+- They have **no awareness** of architectural decisions
+- Every session starts from **zero context**
+- Multiple terminals **don't share knowledge** with each other
+
+## The Solution
+
+**Shadow Brain** runs alongside your agents as a *shadow intelligence layer* with **mythos-level superintelligence**:
+
+1. **Watches** every file change and git commit in real-time
+2. **Analyzes** code using LLM-powered review + rule-based engines + mathematical algorithms
+3. **Learns** patterns, correlations, and recurring issues across sessions
+4. **Injects** insights directly into your agent's memory files
+5. **Scores** your codebase health on every change
+6. **Shares** knowledge across all connected Shadow Brain instances via Quantum Neural Mesh
+
+```
+┌─────────────┐     watches      ┌──────────────┐    injects     ┌─────────────┐
+│  AI Agents  │ ───────────────▶ │ Shadow Brain │ ─────────────▶ │  AI Agents  │
+│ Claude Code │   file changes   │   Analyzer   │  insights +   │   Smarter   │
+│ Kilo Code   │   git commits    │  Health AI   │  context +    │   Safer     │
+│ Cline       │   activity       │  Pattern Mem │  fixes        │   Faster    │
+│ OpenCode    │                  │  Vuln Scan   │               │  Connected  │
+│ Codex       │                  │  Smart Fix   │               │             │
+│ Roo Code    │                  │  Neural Mesh │               │             │
+│ Aider       │                  │  Entropy AI  │               │             │
+└─────────────┘                  └──────────────┘               └─────────────┘
+         ▲                                                              ▲
+         │              ┌──────────────────────┐                       │
+         └──────────────│  Quantum Neural Mesh │───────────────────────┘
+            shares       │  Cross-Session AI   │      shares
+            knowledge    │  Shannon Entropy    │      knowledge
+                         │  Bayesian Inference  │
+                         │  Cosine Similarity   │
+                         └──────────────────────┘
+```
+
+---
+
+## ✨ Features
+
+<table>
+<tr>
+<td width="50%">
+
+### 🧠 Real-Time Intelligence
+- **File watching** — detects changes instantly (chokidar)
+- **Git monitoring** — tracks commits, branches, diffs
+- **LLM-powered analysis** — supports Anthropic, OpenAI, Ollama, OpenRouter
+- **Pattern memory** — learns your codebase patterns over time
+- **Learning engine** — extracts lessons from insights automatically
+
+</td>
+<td width="50%">
+
+### 🔒 Security & Quality
+- **Vulnerability scanner** — npm audit, pip audit, secrets detection
+- **Custom rules engine** — define your own analysis rules (regex-based)
+- **Framework presets** — auto-detects React, Next.js, Django, FastAPI, etc.
+- **Smart fix engine** — auto-generates fix suggestions with confidence scores
+- **Type safety analyzer** — detects `any`, `@ts-ignore`, missing return types
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 📊 Health & Metrics
+- **Health scoring** — A-F grading across 6 dimensions
+- **Code metrics** — LOC, complexity, language breakdown, hotspots
+- **SVG badges** — embeddable health score badges
+- **Trend tracking** — health history with persistence
+- **Performance profiler** — N+1 queries, memory leaks, blocking ops
+
+</td>
+<td width="50%">
+
+### 🔌 Multi-Agent Support (7 Adapters)
+- **Claude Code** — injects into `CLAUDE.md`
+- **Kilo Code** — injects into `.kilocode/rules.md`
+- **Cline** — injects into `.clinerules`
+- **OpenCode** — injects into `AGENT.md`
+- **Codex** — injects into `AGENTS.md`
+- **Roo Code** — injects into `.roo/rules.md`
+- **Aider** — injects into `.aider.conf.yml`
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🚀 Developer Experience
+- **30+ CLI commands** — full control from terminal
+- **MCP Server** — Model Context Protocol for tool integration
+- **Web dashboard** — real-time browser UI at `localhost:7341`
+- **Terminal UI** — Ink/React dashboard in your terminal
+- **Pre-commit hooks** — block bad commits automatically
+- **GitHub Actions** — CI integration with one command
+
+</td>
+<td width="50%">
+
+### 🌐 Super-Intelligence (v2.0+)
+- **Semantic analyzer** — symbol extraction, unused exports, dead code detection
+- **Dependency graph** — cycles, orphans, hub detection with BFS depth analysis
+- **Code similarity** — duplicate/near-duplicate code detection (Winnowing algorithm)
+- **ADR engine** — Architecture Decision Records, auto-detection from changes
+- **Context completion** — identifies missing docs, configs, knowledge gaps
+- **Multi-project** — watch and compare health across multiple repos
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🔔 Notifications & Reports
+- **Slack / Discord / Webhook** — real-time alerts
+- **HTML reports** — beautiful, shareable analysis reports
+- **Markdown reports** — perfect for PR descriptions
+- **PR description generator** — AI-powered PR body generation
+- **Commit message generator** — conventional commits, auto-generated
+
+</td>
+<td width="50%">
+
+### 🧬 Team & Mesh
+- **Team mode** — shared insights and patterns across team members
+- **Quantum Neural Mesh** — cross-session intelligence sharing
+- **SSE real-time updates** — Server-Sent Events for live monitoring
+- **Knowledge base** — shared, deduplicated, relevance-scored
+- **Cross-project patterns** — find common issues across your entire portfolio
+
+</td>
+</tr>
+</table>
+
+---
+
+## 🌌 Quantum Neural Mesh
+
+The Neural Mesh is the breakthrough feature of v2.1.0 — **no such intelligence system has existed before** for AI coding agents. Multiple Shadow Brain instances (running in different terminals, on different projects, with different agents) form a **quantum-entangled neural network** that shares knowledge in real-time.
+
+### Mathematical Foundations
+
+| Algorithm | Application | Formula |
+|---|---|---|
+| **Shannon Entropy** | Relevance scoring for cross-project insights | `H(X) = -Σ p(x) log₂(p(x))` |
+| **Cosine Similarity** | Knowledge deduplication across sessions | `cos(A,B) = (A·B) / (‖A‖·‖B‖)` |
+| **Bayesian Inference** | Confidence updating as evidence accumulates | `P(H\|E) = P(E\|H)·P(H) / P(E)` |
+| **Tarjan's SCC** | Dependency cycle detection | O(V+E) strongly connected components |
+| **BFS Depth Analysis** | Dependency risk scoring | Breadth-first depth = coupling risk |
+| **Winnowing** | Code duplicate fingerprinting | k-gram hashing with window selection |
+
+### How It Works
+
+```
+Terminal 1                    Terminal 2                    Terminal 3
+┌──────────────┐              ┌──────────────┐              ┌──────────────┐
+│ Shadow Brain │              │ Shadow Brain │              │ Shadow Brain │
+│  + Claude    │              │  + Cline     │              │  + Codex     │
+│  + Project A │              │  + Project B │              │  + Project A │
+└──────┬───────┘              └──────┬───────┘              └──────┬───────┘
+       │                             │                             │
+       └─────────────┬───────────────┘                             │
+                     │                 ┌───────────────────────────┘
+                     ▼                 ▼
+            ┌──────────────────────────────┐
+            │   Quantum Neural Mesh Bus    │
+            │   ~/.shadow-brain-mesh/      │
+            │                              │
+            │  • Nodes (heartbeats)        │
+            │  • Messages (insights)       │
+            │  • Knowledge (shared)        │
+            │                              │
+            │  Entropy: 0.73               │
+            │  State: coherent (3 nodes)   │
+            │  Knowledge: 147 entries      │
+            └──────────────────────────────┘
+```
+
+### Mesh States
+
+| State | Nodes | Description |
+|---|---|---|
+| **Coherent** | 3+ | Full quantum coherence — maximum intelligence sharing |
+| **Decoherent** | 1-2 | Partial sharing — limited cross-pollination |
+| **Collapsed** | 0 | Single brain — no mesh connections |
+
+### Mesh CLI Commands
 
 ```bash
-npm install -g @theihtisham/agent-shadow-brain
+# View mesh status — nodes, messages, knowledge, quantum state
+shadow-brain mesh status
+
+# Get cross-session insights from other brains
+shadow-brain mesh insights
+
+# View shared knowledge base
+shadow-brain mesh knowledge
+
+# List all connected brain nodes
+shadow-brain mesh nodes
+
+# Aggregated analytics across all mesh projects
+shadow-brain mesh aggregate
 ```
 
-Or use directly without installing:
+---
+
+### 🎭 Brain Personalities
+
+Choose how Shadow Brain communicates with your agents:
+
+| Personality | Focus | Best For |
+|---|---|---|
+| 🎓 **Mentor** | Teaches & explains patterns | Junior developers, learning |
+| 🔍 **Critic** | Thorough code review | Code quality enforcement |
+| 🏛️ **Architect** | Big-picture design | System design, refactoring |
+| 🛡️ **Security** | Paranoid about vulnerabilities | Security-critical projects |
+| ⚡ **Performance** | Optimization focused | High-performance apps |
+| ⚖️ **Balanced** | All perspectives | Default — recommended |
+
+---
+
+## 🚀 Getting Started
+
+### Install
 
 ```bash
-npx @theihtisham/agent-shadow-brain start .
+# Install globally
+npm install -g @theihtisham/agent-shadow-brain
+
+# Or use with npx (no install)
+npx @theihtisham/agent-shadow-brain review .
 ```
 
-### First-time setup
+### One-Command Setup
 
 ```bash
 shadow-brain setup
 ```
 
-Runs an interactive wizard to configure your LLM provider, personality, and review depth.
+Interactive wizard that configures your LLM provider, personality, and review depth.
 
-### Health check
+### Start Watching
 
 ```bash
-shadow-brain doctor
+shadow-brain start .
 ```
 
-Verifies your configuration, tests provider connectivity, and detects running agents.
+That's it. Shadow Brain will:
+1. Auto-detect which AI agents are running
+2. Start watching your project files
+3. Analyze every change in real-time
+4. Inject insights into your agent's memory
+5. Connect to the Neural Mesh for cross-session intelligence
 
----
+### Enable Neural Mesh (Multiple Terminals)
 
-## How It Works
+```bash
+# Terminal 1 — Project A with Claude Code
+shadow-brain start ./project-a --mesh
 
-<div align="center">
-  <img src="docs/images/architecture.svg" alt="Architecture Diagram" width="100%" />
-</div>
+# Terminal 2 — Project B with Cline
+shadow-brain start ./project-b --mesh
 
-Shadow Brain watches your project files and git activity in real-time, reads what your coding agent is doing, and uses an LLM (with a smart rule-based fallback) to generate insights. It then injects those insights directly into the agent's memory files so the agent picks them up automatically.
+# Terminal 3 — Check mesh status
+shadow-brain mesh status
+```
 
-**Pipeline:** `File/Git Watcher` → `Orchestrator (debounce)` → `Brain Analyzer (LLM + rules)` → `Personality Engine` → `Smart Injection into agent memory`
+What Terminal 1's Shadow Brain learns about security vulnerabilities, Terminal 2 instantly knows too — filtered by relevance using Shannon entropy.
 
-### Key Features
+### Quick Review (No Watch Mode)
 
-- **Real-time monitoring** — watches file changes and git activity as they happen
-- **Multi-provider LLM** — supports Ollama (free/local), Anthropic, OpenAI, and OpenRouter
-- **Smart fallback** — 20+ rule-based patterns work without any LLM (secrets detection, SQL injection, N+1 queries, and more)
-- **6 brain personalities** — mentor, critic, architect, security, performance, or balanced
-- **Auto-injection** — insights go directly into your agent's memory/rules files
-- **5 agent adapters** — works with Claude Code, Kilo Code, Cline, OpenCode, and Codex
-- **3 review depths** — quick (4K), standard (8K), deep (16K tokens)
+```bash
+# One-shot analysis
+shadow-brain review .
 
----
+# With health score and fix suggestions
+shadow-brain review . --show-health --show-fixes
 
-## CLI Reference
+# JSON output for scripting
+shadow-brain review . --output json
+```
 
-### `shadow-brain start [project-dir]`
+---
 
-Start watching a project with a live terminal dashboard.
+## 📖 CLI Reference
+
+### Core Commands
+
+| Command | Description |
+|---|---|
+| `shadow-brain start [dir]` | Start watching in real-time |
+| `shadow-brain review [dir]` | One-shot code analysis |
+| `shadow-brain health [dir]` | Compute health score (A-F grading) |
+| `shadow-brain fix [dir]` | Show smart fix suggestions |
+| `shadow-brain report [dir]` | Generate HTML/MD/JSON report |
+| `shadow-brain metrics [dir]` | Code metrics (LOC, complexity, languages) |
+| `shadow-brain scan [dir]` | Vulnerability scanner |
+| `shadow-brain pr [dir]` | Generate PR description |
+| `shadow-brain commit-msg [dir]` | Generate commit message |
+| `shadow-brain ci [dir]` | Generate GitHub Actions workflow |
+| `shadow-brain hook [dir]` | Install pre-commit hook |
+| `shadow-brain rules [dir]` | Manage custom analysis rules |
+| `shadow-brain dash [dir]` | Web dashboard (port 7341) |
+| `shadow-brain inject <msg>` | Manually inject into agent memory |
+| `shadow-brain notify [dir]` | Test notification channels |
+| `shadow-brain status` | Show current configuration |
+| `shadow-brain config` | Manage configuration |
+| `shadow-brain setup` | Interactive setup wizard |
+| `shadow-brain doctor` | Health check & diagnostics |
+
+### Super-Intelligence Commands (v2.0+)
+
+| Command | Description |
+|---|---|
+| `shadow-brain semantic [dir]` | Semantic analysis — symbols, unused exports, dead code |
+| `shadow-brain deps [dir]` | Dependency graph — cycles, orphans, hubs |
+| `shadow-brain duplicates [dir]` | Detect duplicate/near-duplicate code |
+| `shadow-brain adr [dir]` | Architecture Decision Records |
+| `shadow-brain typesafety [dir]` | TypeScript type safety analysis |
+| `shadow-brain perf [dir]` | Performance profiling |
+| `shadow-brain knowledge [dir]` | Build & view project knowledge base |
+| `shadow-brain gaps [dir]` | Find context gaps (missing docs, configs) |
+| `shadow-brain learn [dir]` | Run learning cycle — extract patterns & lessons |
+| `shadow-brain team share [dir]` | Share insights with team |
+| `shadow-brain team insights` | View team insights |
+| `shadow-brain team stats` | Team activity statistics |
+
+### Neural Mesh Commands (v2.1+)
+
+| Command | Description |
+|---|---|
+| `shadow-brain mesh status` | View mesh state — nodes, knowledge, quantum state |
+| `shadow-brain mesh insights` | Cross-session insights from other brains |
+| `shadow-brain mesh knowledge` | Shared knowledge base |
+| `shadow-brain mesh nodes` | List all connected brain nodes |
+| `shadow-brain mesh aggregate` | Aggregated cross-project analytics |
+
+### Global Options
 
-```bash
-shadow-brain start .                          # Watch current directory
-shadow-brain start . -p anthropic -k $API_KEY # Use Anthropic
-shadow-brain start . --personality security   # Security-focused
-shadow-brain start . --depth deep             # Deep analysis
-shadow-brain start . --agents claude-code,codex  # Watch specific agents
+```
+-p, --provider <provider>    LLM provider: anthropic | openai | ollama | openrouter
+-m, --model <model>          Model name (e.g., claude-sonnet-4-20250514, gpt-4o, llama3)
+-k, --api-key <key>          API key for the provider
+--personality <type>         Brain personality: mentor | critic | architect | security | performance | balanced
+--depth <depth>              Review depth: quick | standard | deep
+--agents <agents>            Comma-separated list of agents to watch
+--no-inject                  Disable auto-injection
+--mesh                       Enable Quantum Neural Mesh
+--team <name>                Enable team mode with username
+--mcp                        Start MCP server alongside
 ```
 
-| Option | Description |
-|--------|-------------|
-| `-p, --provider` | LLM provider: `anthropic`, `openai`, `ollama`, `openrouter` |
-| `-m, --model` | LLM model name |
-| `-k, --api-key` | API key |
-| `--personality` | Brain personality (see below) |
-| `--depth` | Review depth: `quick`, `standard`, `deep` |
-| `--agents` | Comma-separated agent list |
-| `--no-inject` | Disable auto-injection |
+---
 
-### `shadow-brain review [project-dir]`
+## 💻 Programmatic API
 
-One-shot project analysis without watch mode.
+```typescript
+import {
+  Orchestrator,
+  BrainConfig,
+  detectRunningAgents,
+  CodeMetricsEngine,
+  VulnScanner,
+  HealthScoreEngine,
+  SmartFixEngine,
+  CustomRulesEngine,
+  PRGenerator,
+  Notifier,
+  SemanticAnalyzer,
+  DependencyGraphBuilder,
+  CodeSimilarityDetector,
+  ADREngine,
+  TypeSafetyAnalyzer,
+  PerformanceProfiler,
+  LearningEngine,
+  MCPServer,
+  TeamMode,
+  MultiProjectManager,
+  NeuralMesh,
+} from '@theihtisham/agent-shadow-brain';
+
+// Create and start the brain
+const config: BrainConfig = {
+  provider: 'anthropic',
+  projectDir: './my-project',
+  agents: ['claude-code', 'cline', 'roo-code'],
+  watchMode: true,
+  autoInject: true,
+  reviewDepth: 'standard',
+  brainPersonality: 'balanced',
+};
 
-```bash
-shadow-brain review .                  # Text output (default)
-shadow-brain review . --output json    # JSON output
-shadow-brain review . --output markdown # Markdown output
-shadow-brain review . --depth deep     # Thorough analysis
-```
+const brain = new Orchestrator(config);
+
+// Listen to events
+brain.on('insights', ({ insights }) => {
+  console.log(`Generated ${insights.length} insights`);
+});
 
-### `shadow-brain inject <message>`
+brain.on('health-score', ({ score }) => {
+  console.log(`Health: ${score.overall}/100 (${score.grade})`);
+});
 
-Manually inject a message into agent memory.
+brain.on('fixes', ({ fixes }) => {
+  console.log(`${fixes.length} fix suggestions available`);
+});
 
-```bash
-shadow-brain inject "Always use TypeScript strict mode"
-shadow-brain inject "Check for SQL injection" --type warning --priority high
-shadow-brain inject "Follow REST conventions" --agent claude-code
+await brain.start();
+
+// ── Super-Intelligence API (v2.0+) ────────────────────────────────────
+
+// Semantic analysis
+const semantic = await brain.getSemanticInsights(100);
+console.log(`Found ${semantic.unusedExports.length} unused exports`);
+
+// Dependency graph
+const deps = await brain.getDependencyGraph();
+const details = brain.getDependencyDetails(deps);
+console.log(`Cycles: ${details.cycles.length}, Hubs: ${details.hubs.length}`);
+
+// Duplicate detection
+const dupes = await brain.detectDuplicates(0.8);
+console.log(`${dupes.length} duplicate groups found`);
+
+// Type safety
+const typeIssues = await brain.analyzeTypeSafety();
+console.log(`${typeIssues.length} type safety issues`);
+
+// Performance profiling
+const perfInsights = await brain.profilePerformance();
+console.log(`${perfInsights.length} performance suggestions`);
+
+// Learning engine
+await brain.runLearningCycle();
+const lessons = await brain.getLearnedLessons();
+
+// ── Team Mode ────────────────────────────────────────────────────────
+
+brain.enableTeamMode('ihtisham');
+await brain.shareTeamInsight(insights[0]);
+const teamInsights = await brain.getTeamInsights(10);
+
+// ── MCP Server ───────────────────────────────────────────────────────
+
+await brain.startMCPServer({ port: 7342 });
+// Now accessible via JSON-RPC 2.0 at http://localhost:7342/mcp
+
+// ── Neural Mesh (v2.1+) ──────────────────────────────────────────────
+
+const mesh = await brain.enableNeuralMesh();
+console.log(`Connected as node ${mesh.getNodeId()}`);
+
+// Get cross-session insights from other brains
+const crossInsights = brain.getCrossSessionInsights(20);
+console.log(`${crossInsights.length} relevant insights from other sessions`);
+
+// View mesh state
+const state = brain.getMeshState();
+console.log(`Quantum state: ${state?.quantumState}`);
+console.log(`Knowledge entries: ${state?.knowledge.length}`);
+
+// Aggregated analytics
+const aggregated = brain.getAggregatedInsights();
+console.log(`Projects: ${aggregated?.totalProjects}, Patterns: ${aggregated?.crossProjectPatterns.length}`);
+
+// ── Standard API ─────────────────────────────────────────────────────
+
+// Get health score
+const health = await brain.getHealthScore();
+
+// Code metrics
+const metrics = await brain.computeMetrics();
+
+// Vulnerability scan
+const vulns = await brain.runVulnScan();
+
+// Generate PR description
+const pr = await brain.generatePRDescription(changes, 'feature/auth');
+
+// Custom rules
+brain.addCustomRule({
+  id: 'no-console-log',
+  name: 'No Console.Log',
+  description: 'Prevent console.log in production code',
+  pattern: 'console\\.log\\(',
+  severity: 'medium',
+  category: 'quality',
+  enabled: true,
+});
+
+// Notifications
+await brain.sendNotification('critical-insight', 'Security Issue', 'Hardcoded API key found');
 ```
 
-### `shadow-brain status`
+---
 
-Show current configuration and detected agents.
+## 🏗️ Architecture
+
+### Core Components
+
+| Module | File | Purpose |
+|---|---|---|
+| **Orchestrator** | `brain/orchestrator.ts` | Central event loop — coordinates everything |
+| **Analyzer** | `brain/analyzer.ts` | LLM + rule-based code analysis |
+| **LLM Client** | `brain/llm-client.ts` | Multi-provider LLM abstraction (Anthropic, OpenAI, Ollama, OpenRouter) |
+| **Project Context** | `brain/project-context.ts` | Builds project understanding |
+| **Pattern Memory** | `brain/pattern-memory.ts` | Learns codebase patterns |
+| **Health Score** | `brain/health-score.ts` | Multi-dimensional health scoring |
+| **Smart Fix** | `brain/smart-fix.ts` | Auto-generates fix suggestions |
+| **Framework Presets** | `brain/framework-presets.ts` | React, Next.js, Django, FastAPI, etc. |
+| **Custom Rules** | `brain/custom-rules.ts` | User-defined analysis rules |
+| **PR Generator** | `brain/pr-generator.ts` | AI-powered PR/commit messages |
+| **Notifier** | `brain/notifier.ts` | Slack, Discord, Webhook alerts |
+| **Code Metrics** | `brain/code-metrics.ts` | LOC, complexity, language stats |
+| **Vuln Scanner** | `brain/vuln-scanner.ts` | Dependency & secrets scanning |
+| **Report Generator** | `brain/report-generator.ts` | HTML, Markdown, JSON reports |
+| **Auto-Update** | `brain/auto-update.ts` | Version update notifications |
+
+### Super-Intelligence Components (v2.0+)
+
+| Module | File | Purpose |
+|---|---|---|
+| **Semantic Analyzer** | `brain/semantic-analyzer.ts` | Symbol extraction, unused exports, dead code |
+| **Dependency Graph** | `brain/dependency-graph.ts` | Tarjan's SCC, BFS depth, cycle & hub detection |
+| **Code Similarity** | `brain/code-similarity.ts` | Winnowing algorithm for duplicate detection |
+| **ADR Engine** | `brain/adr-engine.ts` | Architecture Decision Records |
+| **Type Safety** | `brain/type-safety.ts` | `any` detection, `@ts-ignore`, missing types |
+| **Performance Profiler** | `brain/perf-profiler.ts` | N+1 queries, memory leaks, blocking ops |
+| **Context Completion** | `brain/context-completion.ts` | Knowledge gaps, missing docs/configs |
+| **Learning Engine** | `brain/learning-engine.ts` | Pattern extraction, lesson persistence |
+| **MCP Server** | `brain/mcp-server.ts` | JSON-RPC 2.0 MCP protocol server |
+| **Team Mode** | `brain/team-mode.ts` | Shared insights & patterns across team |
+| **Multi-Project** | `brain/multi-project.ts` | Watch multiple repos, aggregate health |
+
+### Quantum Neural Mesh (v2.1+)
+
+| Module | File | Purpose |
+|---|---|---|
+| **Neural Mesh** | `brain/neural-mesh.ts` | Cross-session shared intelligence |
+| **Entropy Engine** | `brain/neural-mesh.ts` | Shannon entropy relevance scoring |
+| **Knowledge Bus** | `~/.shadow-brain-mesh/` | Filesystem-based knowledge sharing |
+
+### Adapter Pattern
+
+Each AI agent gets a dedicated adapter that knows how to read its memory files and inject context:
 
-### `shadow-brain config`
+```
+BaseAdapter (abstract)
+├── ClaudeCodeAdapter  → CLAUDE.md, .claude/
+├── KiloCodeAdapter    → .kilocode/rules.md
+├── ClineAdapter       → .clinerules
+├── OpenCodeAdapter    → AGENT.md
+├── CodexAdapter       → AGENTS.md
+├── RooCodeAdapter     → .roo/rules.md
+└── AiderAdapter       → .aider.conf.yml
+```
 
-Manage persistent configuration.
+---
+
+## 🔧 Configuration
+
+### Project Config (`.shadow-brain.json`)
+
+```json
+{
+  "version": "2.1.0",
+  "rules": {
+    "customRules": [
+      {
+        "id": "no-any",
+        "name": "No TypeScript Any",
+        "description": "Prevent usage of 'any' type",
+        "pattern": ":\\s*any\\b",
+        "severity": "medium",
+        "category": "quality",
+        "suggestion": "Use a specific type instead of 'any'",
+        "enabled": true
+      }
+    ],
+    "ignorePaths": ["**/*.test.ts", "**/*.spec.ts"]
+  },
+  "notifications": {
+    "slack": "https://hooks.slack.com/services/...",
+    "discord": "https://discord.com/api/webhooks/...",
+    "onHealthDrop": true,
+    "onCriticalInsight": true
+  },
+  "health": {
+    "weights": {
+      "security": 0.25,
+      "performance": 0.15,
+      "quality": 0.25,
+      "architecture": 0.15,
+      "maintainability": 0.10,
+      "testCoverage": 0.10
+    }
+  }
+}
+```
+
+### Global Config
 
 ```bash
+# Set LLM provider
+shadow-brain config provider anthropic
+
+# Set API key
+shadow-brain config apiKey sk-ant-...
+
+# Set brain personality
+shadow-brain config brainPersonality security
+
+# View all config
 shadow-brain config --list
-shadow-brain config provider openai
-shadow-brain config apiKey sk-xxx
-shadow-brain config personality architect
+
+# Reset to defaults
 shadow-brain config --reset
 ```
 
-### `shadow-brain setup`
+---
+
+## 🔌 GitHub Actions Integration
+
+```bash
+# Generate CI workflow
+shadow-brain ci .
+```
+
+Creates `.github/workflows/shadow-brain.yml` that:
+- Runs Shadow Brain analysis on every PR
+- Posts health score as a PR comment
+- Uploads full HTML report as artifact
+- Runs language-specific lint/test jobs
+- Blocks merge on critical issues
+
+---
 
-Interactive setup wizard for first-time configuration.
+## 🪝 Pre-Commit Hook
 
-### `shadow-brain doctor`
+```bash
+# Install hook
+shadow-brain hook .
 
-Health check — verifies config, tests provider connectivity, detects agents.
+# Remove hook
+shadow-brain hook . --uninstall
+```
+
+Automatically analyzes your staged changes before each commit. If critical issues are found, the commit is blocked. Bypass with `git commit --no-verify`.
 
 ---
 
-## Supported Agents
+## 📊 Health Score System
+
+Shadow Brain computes a multi-dimensional health score (0-100, A-F):
 
-| Agent | Detection | Injection Target |
-|-------|-----------|-----------------|
-| **Claude Code** | `.claude/` directory, process | `.claude/memory/`, `.claude/rules/` |
-| **Kilo Code** | VS Code extension data, `.kilocode/` | `.kilocode/rules/`, `.kilocode/memory/` |
-| **Cline** | VS Code extension data, `.clinerules` | `.clinerules`, `.cline/memory/` |
-| **OpenCode** | `.opencode/`, `opencode.json`, process | `.opencode/rules/`, `AGENTS.md` |
-| **Codex CLI** | `.codex/`, `AGENTS.md`, process | `AGENTS.md` |
+| Dimension | Weight | What It Checks |
+|---|---|---|
+| 🛡️ Security | 25% | Vulnerabilities, secrets, exposed keys |
+| ✨ Quality | 25% | Code smells, anti-patterns, complexity |
+| ⚡ Performance | 15% | N+1 queries, memory leaks, blocking ops |
+| 🏛️ Architecture | 15% | Coupling, cohesion, dependency health |
+| 🔧 Maintainability | 10% | Code duplication, file sizes, comments |
+| 🧪 Test Coverage | 10% | Test presence, assertion quality |
+
+```bash
+# Get health score
+shadow-brain health .
+
+# JSON output
+shadow-brain health . --json
+
+# SVG badge for README
+shadow-brain health . --badge > health-badge.svg
+```
 
 ---
 
-## Brain Personalities
+## 📈 Version History
+
+### v2.1.0 — Quantum Neural Mesh
+- **Neural Mesh** — cross-session shared intelligence between multiple Shadow Brain instances
+- **Shannon entropy** relevance scoring for cross-project insight filtering
+- **Cosine similarity** knowledge deduplication with hash-based vectors
+- **Bayesian confidence** updating as evidence accumulates
+- **5 mesh CLI commands** — status, insights, knowledge, nodes, aggregate
+- **Quantum state** tracking — coherent, decoherent, collapsed
+- **Heartbeat & discovery** — automatic node detection with filesystem bus
+
+### v2.0.0 — Super-Intelligence Edition
+- **Semantic analyzer** — symbol extraction, unused exports, dead code detection
+- **Dependency graph** — Tarjan's SCC algorithm for cycle detection, BFS depth analysis
+- **Code similarity detector** — Winnowing algorithm for duplicate detection
+- **ADR engine** — Architecture Decision Records, auto-detection from changes
+- **Type safety analyzer** — `any` detection, `@ts-ignore`, missing return types
+- **Performance profiler** — N+1 queries, memory leaks, blocking operations
+- **Context completion** — identifies missing documentation, configs, knowledge gaps
+- **Learning engine** — extracts patterns and lessons from project insights
+- **MCP Server** — JSON-RPC 2.0 Model Context Protocol server
+- **Team mode** — shared insights and patterns across team members
+- **Multi-project** — watch and compare health across multiple repos
+- **Roo Code & Aider adapters** — extended agent coverage
+- **11 new CLI commands** — semantic, deps, duplicates, adr, typesafety, perf, knowledge, gaps, learn, team, mesh
+
+### v1.2.0 — Feature Complete
+- **Custom Rules Engine** — define your own analysis rules with regex patterns
+- **PR Description Generator** — AI-powered PR titles and bodies
+- **Commit Message Generator** — conventional commits, auto-generated
+- **Vulnerability Scanner** — npm audit, pip audit, cargo audit, secrets detection
+- **Code Metrics Engine** — LOC, complexity, language breakdown, hotspot detection
+- **Notification System** — Slack, Discord, and webhook alerts for critical findings
+- **Project Config** — `.shadow-brain.json` for per-project settings
+- **Auto-Update Checker** — notifies when a new version is available
 
-<div align="center">
-  <img src="docs/images/personalities.svg" alt="Brain Personalities" width="100%" />
-</div>
+---
 
-| Personality | Focus |
-|------------|-------|
-| `mentor` | Teaches and explains — code quality, best practices, learning tips |
-| `critic` | Thorough code reviews — bugs, logic errors, edge cases, dead code |
-| `architect` | Big-picture thinking — modularity, scalability, design patterns |
-| `security` | Paranoid about vulnerabilities — OWASP top 10, injection attacks, secret leaks |
-| `performance` | Optimization focused — N+1 queries, memory leaks, bundle size |
-| `balanced` | Mix of all perspectives (default) |
+## 🤝 Supported Agents
+
+| Agent | Status | Injection Target |
+|---|---|---|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | ✅ Full Support | `CLAUDE.md`, `.claude/` |
+| [Kilo Code](https://kilocode.ai/) | ✅ Full Support | `.kilocode/rules.md` |
+| [Cline](https://github.com/cline/cline) | ✅ Full Support | `.clinerules` |
+| [OpenCode](https://github.com/opencode-ai/opencode) | ✅ Full Support | `AGENT.md` |
+| [Codex](https://github.com/openai/codex) | ✅ Full Support | `AGENTS.md` |
+| [Roo Code](https://roocode.com/) | ✅ Full Support | `.roo/rules.md` |
+| [Aider](https://aider.chat/) | ✅ Full Support | `.aider.conf.yml` |
+| [Cursor](https://cursor.com/) | 🔄 Planned | — |
 
 ---
 
-## Rule-Based Detection Patterns
+## 🛠️ Development
 
-Even without an LLM configured, Shadow Brain detects **20+ code patterns**:
+```bash
+# Clone
+git clone https://github.com/theihtisham/agent-shadow-brain.git
+cd agent-shadow-brain
 
-**Security:** hardcoded secrets, API keys, private keys, SQL injection, XSS (dangerouslySetInnerHTML), eval/Function usage, .env file changes, database credential exposure
+# Install dependencies
+npm install
 
-**Code Quality:** large batch changes, deleted files, code changes without tests, missing .gitignore, missing tsconfig.json, framework mismatches, excessive console.log
+# Build
+npm run build
 
-**Performance:** N+1 query patterns, synchronous file I/O, async/await in loops
+# Run in dev mode
+npm run dev start .
 
-**Architecture:** multiple config file changes, database migrations, infrastructure/deployment files, API endpoint changes, lock file drift
+# Run tests
+npm test
+
+# Type check
+npm run lint
+```
 
 ---
 
-## LLM Providers
+## 🗺️ Roadmap
 
-| Provider | Setup | Cost |
-|----------|-------|------|
-| **Ollama** (default) | `ollama serve` + `ollama pull llama3` | Free, local |
-| **Anthropic** | Set API key via `shadow-brain config apiKey sk-...` | Pay per token |
-| **OpenAI** | Set provider + API key | Pay per token |
-| **OpenRouter** | Set provider + API key | Pay per token |
+- [x] ~~**MCP Server Mode** — run as a Model Context Protocol server~~ (v2.0)
+- [x] ~~**Multi-project support** — watch multiple repos simultaneously~~ (v2.0)
+- [x] ~~**Team mode** — shared pattern memory across team members~~ (v2.0)
+- [x] ~~**Roo Code & Aider adapters** — extend agent coverage~~ (v2.0)
+- [x] ~~**Cross-session intelligence** — Neural Mesh quantum sharing~~ (v2.1)
+- [ ] **IDE extensions** — VS Code extension for inline insights
+- [ ] **Custom LLM fine-tuning** — train on your codebase patterns
+- [ ] **Docker image** — one-command containerized deployment
+- [ ] **Web dashboard v2** — React-based interactive analytics dashboard
+- [ ] **Language server** — LSP protocol for real-time inline feedback
 
 ---
 
-## Programmatic API
+## 📄 License
 
-```typescript
-import { Orchestrator, createAdapter, LLMClient, Analyzer, PromptBuilder } from '@theihtisham/agent-shadow-brain';
+MIT License — see [LICENSE](LICENSE) for details.
 
-const orchestrator = new Orchestrator({
-  provider: 'ollama',
-  projectDir: '/path/to/project',
-  agents: ['claude-code'],
-  watchMode: true,
-  autoInject: true,
-  reviewDepth: 'standard',
-  brainPersonality: 'balanced',
-});
+---
 
-orchestrator.on('insights', ({ insights }) => {
-  console.log('Generated insights:', insights);
-});
+## 👤 Author
 
-await orchestrator.start();
-```
+**theihtisham**
+
+[![GitHub](https://img.shields.io/badge/GitHub-theihtisham-181717?style=flat-square&logo=github)](https://github.com/theihtisham)
+[![npm](https://img.shields.io/badge/npm-@theihtisham-CB3837?style=flat-square&logo=npm)](https://www.npmjs.com/~theihtisham)
 
 ---
 
-## Contributing
+<div align="center">
+
+### If Shadow Brain makes your AI agents smarter, give it a ⭐
+
+[![Star History Chart](https://api.star-history.com/svg?repos=theihtisham/agent-shadow-brain&type=Date)](https://star-history.com/#theihtisham/agent-shadow-brain&Date)
 
-1. Fork the repository
-2. Create your feature branch: `git checkout -b feature/my-feature`
-3. Commit your changes: `git commit -m 'Add my feature'`
-4. Push to the branch: `git push origin feature/my-feature`
-5. Open a Pull Request
+**Built with 🧠 by [theihtisham](https://github.com/theihtisham)**
 
-## License
+</div>
+
+---
 
-[MIT](LICENSE) © 2025 theihtisham
+<div align="center">
+
+**Topics:** `ai` `artificial-intelligence` `llm` `claude-code` `cline` `kilo-code` `codex` `roo-code` `aider` `opencode` `code-review` `static-analysis` `developer-tools` `npm-package` `typescript` `ollama` `openai` `anthropic` `code-quality` `security-scanner` `health-score` `smart-fix` `vulnerability-scanner` `pattern-learning` `agent-tools` `ai-agent` `code-metrics` `pre-commit-hook` `github-actions` `developer-productivity` `shadow-ai` `neural-code-review` `auto-review` `intelligence-layer` `multi-agent` `ai-coding-assistant` `devtools` `cli-tool` `code-analysis` `software-quality` `tech-debt` `ai-tools` `prompt-engineering` `agentic-coding` `vibe-coding` `ai-engineering` `llm-tools` `ai-workflow` `code-intelligence` `neural-mesh` `quantum-computing` `shannon-entropy` `bayesian-inference` `mcp-server` `semantic-analysis` `dependency-graph` `team-collaboration` `cross-session` `super-intelligence`
+
+</div>