@theihtisham/agent-shadow-brain

The World's #1 Infinite-Intelligence AI Coding Brain

Shadow Brain is a zero-config, self-evolving, infinite-memory intelligence layer that makes every AI coding agent write better, safer, faster code. Install it once, and it automatically detects your project, your AI tools, your frameworks — and starts making your agents smarter forever.

v5.0.1 — Infinite Intelligence Edition: Zero-config auto-setup with MCP server for Claude Code + Cursor + 8 AI tools, rich web dashboard with real-time WebSocket updates, natural language brain queries, plugin system, brain export/import for team sync, git hook integration, and all v5.0.0 infinite intelligence features — 4-tier hierarchical memory, context-triggered associative recall, multi-agent consensus, collective cross-project learning, TurboQuant 6x compression, SSSP routing, self-evolving genetic rules, adversarial hallucination defense, swarm intelligence, knowledge graph with PageRank, and predictive bug forecasting.

Install Now · Dashboard · v5.0.1 New · Algorithms · CLI Reference · Architecture

The Problem

You use AI coding agents. They're powerful, but:

The Solution

Shadow Brain v5.0.1 — zero-config, auto-detecting, infinite-intelligence shadow layer:

┌──────────────┐    auto-detect     ┌──────────────────────────────────────────┐
│  AI Agents   │ ◀────────────────  │         SHADOW BRAIN v5.0.1              │
│ Claude Code  │  MCP auto-install  │                                          │
│ Cursor       │  zero-config       │  ┌─ ZERO-CONFIG (v5.0.1 NEW) ────────┐  │
│ Kilo Code    │                    │  │ Auto-detect project, tools, langs  │  │
│ Cline        │    watches         │  │ MCP server for ALL AI tools        │  │
│ OpenCode     │ ──────────────▶   │  │ Rich web dashboard (real-time)     │  │
│ Codex        │  file changes      │  │ Natural language brain queries     │  │
│ Roo Code     │  git commits       │  │ Plugin system + export/import      │  │
│ Aider        │  activity          │  └────────────────────────────────────┘  │
│ Windsurf     │                    │  ┌─ INFINITE MEMORY (v5.0.0) ────────┐  │
└──────────────┘                    │  │ 4-tier hierarchical compression    │  │
         ▲                          │  │ Context-triggered recall            │  │
         │                          │  │ Multi-agent consensus + trust       │  │
         │                          │  │ Collective cross-project learning   │  │
         │                          │  └────────────────────────────────────┘  │
         │                          │  ┌─ HYPER-INTELLIGENCE (v4) ──────────┐  │
         │                          │  │ TurboQuant 6x Compression           │  │
         │                          │  │ SSSP BMSSP Quantum Routing          │  │
         │                          │  │ Self-Evolution + CAIP + Swarm       │  │
         │                          │  │ PageRank + Predictive + Adversarial │  │
         └──────────────────────────┴──────────────────────────────────────────┘

v5.0.1 — What's New

Zero-Config Auto-Setup

Install it. That's it. Shadow Brain automatically:

• Detects your project type (frontend, backend, fullstack, mobile, game, systems, data-science)
• Detects 25+ languages, 15+ frameworks, 5+ build tools, 5+ test frameworks
• Detects which AI tools are installed (Claude Code, Cursor, Kilo Code, Cline, OpenCode, Codex, Aider, Windsurf)
• Auto-installs MCP server configuration for every detected AI tool
• Auto-installs git pre-commit and pre-push hooks
• Generates an optimal brain config based on project complexity

npm install @theihtisham/agent-shadow-brain
# → Shadow Brain v5.0.1 auto-configured for my-app (fullstack)
# → AI tools detected: Claude Code, Cursor
# → Run: shadow-brain start

MCP Server — Works with EVERY AI Tool

The brain exposes itself as a Model Context Protocol (MCP) server with 19 tools that any AI tool can call:

Works with Claude Code, Cursor, Kilo Code, Cline, OpenCode, and any MCP-compatible AI tool.

# Start MCP server (auto-started by AI tools)
shadow-brain mcp

# Cursor compatibility (root path POST + /v1/chat)
# Claude Code compatibility (JSON-RPC 2.0 over stdio/HTTP)

Rich Web Dashboard

Real-time browser dashboard at http://localhost:7341 with WebSocket live updates:

• Stats Topbar: 8 live counters — Insights, Fixes, Memory KB, Modules, AI Tools, Evolution Gen, Swarm Convergence, Turbo Compression
• Health Score: A-F grading with dimension breakdown (Security, Quality, Performance, Architecture, Maintainability, Test Coverage)
• Memory Tiers: Visual bars showing Raw (50K), Summary (10K), Pattern (2K), Principle (500) with Turbo compression ratio
• Live Insights Stream: Real-time feed of brain insights with priority badges
• Smart Fixes: Actionable fix suggestions with file/line references
• AI Tools Panel: 8 tools showing connected/detected status
• Brain Modules: 13 modules with active/idle/error indicators
• Control Buttons: Trigger analysis on-demand, refresh data

shadow-brain start .     # Dashboard auto-starts at http://localhost:7341
shadow-brain dash .      # Dashboard only mode

Natural Language Queries

Ask your brain questions in plain English:

shadow-brain ask "What security issues exist in the auth module?"
shadow-brain ask "Which files have the highest bug risk?"
shadow-brain ask "What patterns have we learned about React hooks?"

Brain Export/Import — Team Sync

Export your brain state and share it with your team:

shadow-brain export                    # Full export with all modules
shadow-brain export -o ./team-brain    # Custom output directory
shadow-brain import brain-export.json  # Import + merge
shadow-brain import brain-export.json --merge --skip swarm,evolution

Plugin System

Extend Shadow Brain with custom plugins:

shadow-brain plugin list               # List installed plugins
shadow-brain plugin create my-plugin   # Create from template
shadow-brain plugin stats              # Plugin system statistics

Plugins can hook into pre-analysis and post-analysis pipelines to add custom insights, filter results, or integrate with external services.

5 New Commands

shadow-brain off          # Clean shutdown
shadow-brain ask "..."    # Natural language query
shadow-brain export       # Export brain state
shadow-brain import FILE  # Import brain state
shadow-brain plugin CMD   # Plugin management

Getting Started — 30 Seconds

# Install globally
npm install -g @theihtisham/agent-shadow-brain

# Or use npx (no install needed)
npx @theihtisham/agent-shadow-brain start .

That's literally it. Shadow Brain will:

1. Auto-detect your project, languages, frameworks, AI tools (zero config)
2. Auto-install MCP server config for Claude Code, Cursor, Kilo Code, Cline, etc.
3. Auto-install git hooks for pre-commit and pre-push
4. Watch your project files for changes
5. Analyze every change with LLM + 13 brain modules
6. Inject expert insights into your agent's memory
7. Store all knowledge in hierarchical memory for infinite retention
8. Activate past memories automatically based on context
9. Share verified patterns across projects via collective learning
10. Compress knowledge with TurboQuant for infinite retention
11. Evolve its own rules via genetic algorithm
12. Share insights across agents via CAIP
13. Detect hallucinations with adversarial verification
14. Run consensus when multiple agents disagree
15. Serve a rich web dashboard at localhost:7341

Quick Review (No Watch Mode)

shadow-brain review .                    # One-shot analysis
shadow-brain review . --show-health      # + health score
shadow-brain review . --show-fixes       # + fix suggestions
shadow-brain review . --output json      # JSON for scripting

Web Dashboard

The v5.0.1 dashboard provides a real-time view into your brain:

┌──────────────────────────────────────────────────────────────────────────┐
│  Shadow Brain v5.0.1                                     [Analyze] [↻] │
├──────────────────────────────────────────────────────────────────────────┤
│  Insights: 142 │ Fixes: 38 │ Memory: 247KB │ Modules: 13/13 │ ...     │
├──────────────┬─────────────────────────────────────┬───────────────────┤
│ Health: 87%  │  Live Insights Stream               │ AI Tools          │
│ ████████░░   │  ● [HIGH] SQL injection in login.ts │ ● Claude Code ✓  │
│ Security: A  │  ● [MED] Missing error handling     │ ● Cursor    ✓    │
│ Quality: B+  │  ● [LOW] Unused import in utils     │ ● Kilo Code ✓    │
│ Perf:    A-  │  ● [CRIT] Exposed API key           │ ● Cline     —    │
│ Arch:    B   │                                     │ ● OpenCode  —    │
│ Maintain: A  ├─────────────────────────────────────┤ ● Codex     —    │
│ Tests:   C+  │  Smart Fixes                        │ ● Aider     —    │
│              │  1. Add parameterized query...       │ ● Windsurf  —    │
├──────────────┤  2. Wrap in try/catch with...       ├───────────────────┤
│ Memory Tiers │  3. Remove unused import on L42     │ Brain Modules     │
│ Raw:   8421  │                                     │ ● Hierarchical ✓  │
│ Summ:  1203  │                                     │ ● TurboMemory  ✓  │
│ Patt:   187  │                                     │ ● Consensus    ✓  │
│ Princ:    24 │                                     │ ● Swarm        ✓  │
│ Turbo: 6.2x  │                                     │ ● Evolution    ✓  │
│              │                                     │ ● Adversarial  ✓  │
└──────────────┴─────────────────────────────────────┴───────────────────┘

v5.0.0 Infinite Intelligence Engine

4 Breakthrough Modules

shadow-brain memory stats          # 4 tiers | 12,847 entries
shadow-brain memory store "..."    # Store new knowledge
shadow-brain memory search "auth"  # Cross-tier semantic search

shadow-brain recall . --file src/auth/login.ts --keywords "jwt,session"
# → Activates 8 memories | Top: "JWT rotation pattern (92%)"

shadow-brain consensus status
shadow-brain consensus propose "Use bcrypt for all password hashing" security 0.95
shadow-brain consensus vote <id> agree 0.9 "Industry standard"
shadow-brain consensus results

shadow-brain collective status
shadow-brain collective propose "Always validate file upload MIME types" security
shadow-brain collective search performance

v4.0.0 Hyper-Intelligence Engine

8 Breakthrough Modules (included in v5.0.1)

shadow-brain turbo stats
shadow-brain turbo search "authentication patterns"

shadow-brain route status
shadow-brain route find node-A node-B

shadow-brain evolve status
shadow-brain evolve run
shadow-brain evolve best-rules security

shadow-brain caip status
shadow-brain caip broadcast "Security pattern detected"

shadow-brain defense status
shadow-brain defense scan "This API endpoint exists at /api/v2/users"

shadow-brain swarm status
shadow-brain swarm priorities

shadow-brain graph build .
shadow-brain graph pagerank
shadow-brain graph cycles

shadow-brain predict bugs .

Algorithms & Research

Shadow Brain v5.0.1 implements algorithms from peer-reviewed research:

TurboQuant Pipeline Detail

Input Vector (64-dim, float64)
     |
     v
+-------------+
|  PolarQuant  |-- Cartesian -> Polar coordinates
|  2 bits/dim  |-- Quantize angles to 4 levels (2 bits each)
+------+-------+   Pack into Uint8Array
       |
       v
+-------------+
|  QJL Residual|-- Random rotation (Hadamard-like)
|  1 bit/dim   |-- Sign extraction (1 bit per dim)
+------+-------+   Pack into Uint8Array
       |
       v
  TurboVector { polar: Uint8Array, qjl: Uint8Array, dim: number, radius: number }
  = 3 bits/dim total = 6x compression from float64
  = ZERO FORGETTING -- compressed knowledge stays searchable forever

Features

Architecture

v5.0.1 Module Map (16 modules)

CLI Reference

Core Commands

v5.0.1 Commands (NEW)

v5.0.0 Infinite Intelligence Commands

v4.0.0 Hyper-Intelligence Commands

Programmatic API

import {
  Orchestrator,
  AutoSetup,
  PluginSystem,
  BrainPortability,
  HierarchicalMemory,
  ContextRecall,
  ConsensusEngine,
  CollectiveLearning,
  TurboMemory,
  SSSPRouter,
  SelfEvolution,
  CrossAgentProtocol,
  AdversarialDefense,
  SwarmIntelligence,
  KnowledgeGraph,
  PredictiveEngine,
  NeuralMesh,
} from '@theihtisham/agent-shadow-brain';

// v5.0.1 — Zero-config auto-setup
const setup = new AutoSetup('./my-project');
const config = await setup.detect();
// → { projectType: 'fullstack', languages: ['typescript','python'], frameworks: ['next.js'], aiTools: [...] }
await setup.installMCPForTools(['Claude Code', 'Cursor']);
await setup.installGitHooks();

// Create the brain
const brain = new Orchestrator({
  provider: 'anthropic',
  projectDir: './my-project',
  agents: ['claude-code', 'cursor', 'cline'],
  watchMode: true,
  autoInject: true,
  brainPersonality: 'balanced',
});

// v5.0.1 — Plugin system
const plugins = new PluginSystem('./my-project');
await plugins.loadAll();
await plugins.preAnalysis({ files: ['src/auth.ts'], projectDir: './my-project' });

// v5.0.1 — Brain portability
const porter = new BrainPortability('./my-project');
const { filePath, sizeBytes, checksum } = await porter.exportBrain();

// v5.0.0 — Infinite Intelligence
const hmem = new HierarchicalMemory();
await hmem.store('JWT rotation pattern: rotate every 24h with refresh tokens', 'security', 0.9);
const results = hmem.search('jwt');

const recall = new ContextRecall(hmem);
const activated = recall.recall({
  currentFile: 'src/auth/login.ts',
  currentCategory: 'security',
  recentEdits: ['src/auth/login.ts', 'src/middleware/auth.ts'],
  projectType: 'node',
  keywords: ['jwt', 'authentication', 'session'],
});

const consensus = new ConsensusEngine('my-agent');
const proposalId = consensus.propose('Use bcrypt cost factor 12', 'security', 0.95);

// Start everything
await brain.start();

Health Score System

Version History

v5.0.1 — Zero-Config Intelligence Edition (Current)

• Zero-Config Auto-Setup — auto-detect project, AI tools, languages, frameworks; auto-install MCP config + git hooks
• MCP Server — 19-tool Model Context Protocol server for Claude Code, Cursor, and all AI tools
• Rich Web Dashboard — real-time WebSocket dashboard with 8 panels (health, memory tiers, insights, fixes, AI tools, modules, stats, controls)
• Natural Language Queries — shadow-brain ask "..." for plain-English brain interaction
• Plugin System — hookable analysis pipeline with npm plugin discovery
• Brain Export/Import — full brain state portability for team sync and backup
• 5 new CLI commands — off, ask, export, import, plugin
• Cursor MCP Compatibility — root path POST + /v1/chat endpoint support
• Postinstall Auto-Setup — runs automatically after npm install
• 50+ npm keywords for discoverability
• All v5.0.0 and v4.0.0 features included and enhanced

v5.0.0 — Infinite Intelligence Edition

• Hierarchical Memory Compression — 4-tier pyramid (raw -> summary -> pattern -> principle) with drill-down/up
• Context-Triggered Associative Recall — automatic memory activation based on file paths, keywords, categories
• Multi-Agent Consensus Protocol — trust-weighted voting, confidence intervals, conflict resolution
• Collective Cross-Project Learning — verified rule sharing, viral propagation, accuracy tracking
• 5 new CLI commands — memory, recall, consensus, collective, v5

v4.0.0 — Hyper-Intelligence Edition

• TurboQuant Infinite Memory — 6x compression, zero forgetting (Google Research, ICLR 2026)
• SSSP BMSSP Routing — O(m log^2/3n) deterministic routing (arXiv 2504.17033)
• Self-Evolving Genetic Rules — tournament selection, Gaussian mutation, Bayesian meta-learning
• Cross-Agent Intelligence Protocol — 7 agents share insights in real-time
• Adversarial Hallucination Defense — cross-reference verification, evidence scoring
• Swarm Intelligence — Ant Colony pheromone file prioritization
• Knowledge Graph + PageRank — code impact radar with d=0.85 damping
• Predictive Engine — bug risk scoring, debt forecasting, anomaly detection

v3.0.0 — Hyper-Intelligence Edition

• Cognitive load analysis, security audit engine, influence map

v2.1.0 — Quantum Neural Mesh

• Cross-session shared intelligence, Shannon entropy, cosine similarity, Bayesian confidence

v2.0.0 — Super-Intelligence Edition

• Semantic analyzer, dependency graph, code similarity, MCP Server, team mode

v1.x — Foundation

• 7 agent adapters, health scoring, smart fixes, vulnerability scanning, CI/CD

Supported Agents & Tools

Development

git clone https://github.com/theihtisham/agent-shadow-brain.git
cd agent-shadow-brain
npm install
npm run build
npm test

Roadmap

• MCP Server, multi-project, team mode (v2.0)
• Cross-session neural mesh (v2.1)
• TurboQuant infinite memory (v4.0)
• SSSP quantum routing (v4.0)
• Self-evolving rules (v4.0)
• Cross-agent protocol (v4.0)
• Adversarial hallucination defense (v4.0)
• Hierarchical memory compression (v5.0)
• Context-triggered associative recall (v5.0)
• Multi-agent consensus protocol (v5.0)
• Collective cross-project learning (v5.0)
• Zero-config auto-setup (v5.0.1)
• MCP server for Cursor + all tools (v5.0.1)
• Rich web dashboard with real-time WebSocket (v5.0.1)
• Plugin system + brain export/import (v5.0.1)
• IDE extensions — VS Code extension for inline insights
• Custom LLM fine-tuning — train on your codebase patterns
• Docker image — one-command containerized deployment
• Language server — LSP protocol for real-time feedback
• Web dashboard v3 — collaborative team dashboard

License

MIT License — see LICENSE for details.

Author

theihtisham