.png)
🎬 2-minute explainer above — auto-plays muted · click 🔊 to unmute · or open on Release page
Claude Code · Cursor · Cline · Codex · Copilot · Windsurf · Kilo · Roo · OpenCode · Aider — all running on one local brain. What one agent learns, every agent knows. What one sub-agent discovers, every sub-agent inherits.
# 30 seconds. Every agent + sub-agent on your machine becomes smarter.
npx @theihtisham/agent-shadow-brain@latest attach-all🎬 Video · 📦 npm · ⭐ Star on GitHub · 📚 Docs · 🐛 Issues
# Method 1 — one command, every agent wired, dashboard launches
npx @theihtisham/agent-shadow-brain@latest attach-all
# Method 2 — global install
npm install -g @theihtisham/agent-shadow-brain
shadow-brain attach-all
shadow-brain dash . # → http://localhost:7341/
# Method 3 — in a specific project only
cd my-project
npx @theihtisham/agent-shadow-brain attach-allZero config. Zero API key required. 100 % local-first.
| Without Shadow Brain | With Shadow Brain v6 |
|---|---|
| Every new session → agent starts from zero | 2K-token briefing injected before the first prompt |
| Cursor learns X → Claude doesn't know | One singleton brain every agent shares |
| Claude Task spawns sub-agent → sub-agent starts blind | SABB injects focused context slivers into every sub-agent |
| You can't explain why the AI made a choice | Causal Memory Chains render the full DAG of causes |
| Two agents touching the same file = merge hell | Collision Detective catches it in real time |
| Agents work, then go idle — wasted compute | Dream Engine reflects during idle, runs counterfactuals |
| No verifiable record of agent decisions | Ed25519-signed Reputation Ledger — tamper-proof receipts |
| Token bills explode across Opus / GPT / Gemini | Token Economy routes to cheapest model that passes confidence |
| Needs its own API key for everything | Agent-proxy mode reuses your existing Claude/Cursor/Codex config |
| Every tool runs hot, every key leaks | Air-Gap mode + ChaCha20 encryption at rest |
This isn't a wrapper around someone else's API. All 22 are first-party research-grade implementations, persisted to disk, with real tests.
- Sub-Agent Brain Bridge (SABB) — sync brain context into Claude Task / Cursor Composer / CrewAI / LangGraph / AutoGen sub-agents
- Causal Memory Chains — every decision links to its causes; Graphviz DOT export
- Dream Engine — idle-time reflection: revisit / counterfactual / consolidation / contradiction / pattern-discovery
- Swarm Debate Protocol — pro / con / arbiter sub-agents for critical decisions
- Pre-Mortem Assistant — surfaces past failures from your project before you start
- Branch Brains — git-branch-aware memory context
- Agent Reputation Ledger — Ed25519-signed receipts, portable accuracy score
- Attention Heatmap — weighted attribution showing which memories shaped a decision
- Confidence Calibration Monitor — Brier scores + automatic trust-weighting
- Formal Verification Bridge — natural-language rules → ESLint / Semgrep / LSP diagnostics
- Agent Collision Detective — real-time overlap detection with advisory locks
- Token Economy Engine — cross-agent spend, savings suggestions, routing advice
- Cost-Aware Sub-Agent Spawner — auto-route trivial tasks to cheaper models
- Forgetting Curve + Sleep Consolidation — Ebbinghaus-inspired biological memory
- Air-Gap Mode — zero outbound network, localhost-only
- E2E Encryption — ChaCha20-Poly1305 at rest
- Hallucination Quarantine — isolate suspect memories, auto-expire in 7 days
- Voice Mode — natural-language intent parser for transcripts
- Brain Garden — animated visualization of memory as a living constellation
- PR Auto-Review — GitHub PR comments citing project memories
- Team Brain Sync (WebRTC) — peer-to-peer shared brain, no server
- Brain Exchange — export / import curated shareable brain slices
- Local-First LLM — Ollama default; optional Anthropic / OpenAI / OpenRouter / Moonshot / Gemini / DeepSeek / Mistral
- Hive Accelerator — SSSP (arXiv 2504.17033) + TurboQuant (ICLR 2026) for fast causal traversal + 6× vector compression
Start it:
shadow-brain dash .
# → http://localhost:7341/28 tabs. Real-time data. Full control. Every feature has live monitoring + interactive controls. Preview:
 |
 |
 |
| Overview — live counters, charts | Live Graph — animated signal flow | Agents — connect / disconnect per agent |
 |
 |
 |
| Chat with Brain — RAG with citations | Memory Browser — semantic search | SABB — sliver generator + quarantine |
 |
 |
 |
| Causal Chains — traceable decisions | Dream Engine — reflection insights | Reputation — Ed25519 leaderboard |
 |
 |
 |
| Token Economy — $ saved live | Models & Intelligence — 8 providers | ⌘K Command Palette |
→ Browse all 29 tab screenshots
Features: dark + light theme · command palette (⌘K) · keyboard shortcuts · toast notifications · Chart.js analytics · responsive (mobile / tablet / desktop) · real-time WebSocket · stop button that actually stops the process.
| Agent | Adapter | Hook target |
|---|---|---|
| Claude Code | ✅ Native | ~/.claude/settings.json hooks.SessionStart |
| Cursor | ✅ Native | .cursor/rules/shadow-brain.md + MCP |
| Cline | ✅ Native | VS Code globalStorage MCP |
| Codex | ✅ Native | ~/.codex/config.json |
| GitHub Copilot | ✅ Native | .github/copilot-instructions.md |
| Windsurf | ✅ Native | .windsurfrules + MCP |
| Kilo Code | ✅ Native | ~/.kilocode/settings.json |
| Roo Code | ✅ Native | ~/.roocode/mcp.json |
| OpenCode | ✅ Native | AGENT.md |
| Aider | ✅ Native | .aider.conf.yml |
Custom agent? Add its config path in the dashboard "Custom Agent Paths" panel — Shadow Brain will auto-read its provider + model + API key.
Sub-agent frameworks supported by SABB: Claude Task, Cursor Composer, Cline Sub-step, CrewAI, LangGraph, AutoGen, generic.
Shadow Brain's ModelRegistry supports 8 providers out of the box:
Ollama (default, local, free) · Anthropic Claude · OpenAI · OpenRouter · Moonshot / Kimi · Google Gemini · DeepSeek · Mistral
Plus a unique Agent Proxy mode: if you already use Claude Code / Cursor / Codex with their own API key, Shadow Brain borrows their intelligence — zero new API keys, zero cost.
Auto-discovery reads every agent config on your machine so you never retype a key.
| Metric | Value |
|---|---|
| Brain modules | 48 |
| CLI commands | 90+ |
| MCP tools | 60+ |
| REST endpoints | 50+ |
| Tests passing | 148 / 148 |
| TypeScript errors | 0 |
| Supported agents | 10 (plus custom) |
| Supported LLM providers | 8 (plus agent-proxy) |
| Novel features nobody else has | 22 |
| License | MIT |
| Cost to run | $0 forever (local-first) |
# 1. Install
npx @theihtisham/agent-shadow-brain@latest attach-all
# 2. Launch the dashboard
shadow-brain dash .
# → open http://localhost:7341/
# 3. Seed the brain (optional — populates example data)
shadow-brain reputation sign --agent claude-code --ver 4.7 --project demo \
--decision "use bcrypt cost 12 for all password hashing" \
--category security --confidence 0.92
# 4. Every new AI agent session automatically gets context injectedThat's it. Open any project in Claude Code / Cursor / any supported agent — Shadow Brain is already running under the hood.
▶ Click here to watch · Full motion graphics explainer with voice-over walking through every feature, the live dashboard, and the 30-second install.
Local file: docs/launch/shadow-brain-motion-explainer-narrated.mp4 (2:05 · 1080p · narrated).
# Attachment + lifecycle
shadow-brain attach-all # wire every detected agent
shadow-brain detach-all # remove every hook
shadow-brain audit-hooks # list what's installed
shadow-brain dash . # launch web dashboard at :7341
shadow-brain mcp # start MCP server at :7342
# v6 Hive Mind
shadow-brain hive status # cross-module status
shadow-brain subagent sliver --parent claude-code --task "refactor auth"
shadow-brain causal trace <id> # render ancestor DAG
shadow-brain dream run # trigger idle reflection now
shadow-brain debate "Redis or Postgres?" --context "10k users"
shadow-brain premortem "migrate auth to passkeys"
shadow-brain reputation sign --agent claude-code --ver 4.7 --project X \
--decision "..." --category security --confidence 0.92
shadow-brain reputation badge claude-code --ver 4.7
# Memory + analytics
shadow-brain global recall --keywords "auth"
shadow-brain tokens report # cross-agent spend + savings
shadow-brain forget consolidate # run sleep cycle
shadow-brain formal generate "always use parameterized SQL"
shadow-brain formal export-eslint
# Privacy + trust
shadow-brain airgap enable --policy strict
shadow-brain encrypt file ~/.shadow-brain/global.json --passphrase ...
shadow-brain quarantine list
# Sharing
shadow-brain exchange export --name "react-expert-v1" --tags react,auth
shadow-brain exchange import ~/brain-packs/react-expert-v1.json
# Full list
shadow-brain --help"Shadow Brain is the first open-source brain that works with sub-agents. Claude Task, Cursor Composer, CrewAI, LangGraph, AutoGen — all finally share context. One
npxcommand. Zero API keys."
"Every AI decision Shadow Brain makes is Ed25519-signed. Every cause is traced. Every collision is caught before it happens. Free forever."
"22 novel features nobody else has. Free. Open source. Local-first.
npx @theihtisham/agent-shadow-brain."
git clone https://github.com/theihtisham/agent-shadow-brain.git
cd agent-shadow-brain
npm install
npm run build
npm test # 148/148 tests
npm run dev # ts-node dev mode
# Rebuild the explainer video
node tools/record-motion-explainer.mjs
# Capture fresh dashboard screenshots
node tools/capture-screenshots.mjs
# Seed the brain with demo data
node tools/seed-brain.mjsIssues, PRs, discussions welcome. See CONTRIBUTING.md.
- CHANGELOG.md — release notes
- docs/versions/v6.0.0.md — v6 release details
- docs/launch/HIVEMIND_VIDEO.md — video production pipeline
- docs/launch/screenshots/ — all 29 dashboard screenshots
- SECURITY.md — security policy
- CODE_OF_CONDUCT.md — community guidelines
- GitHub Issues — bug reports, feature requests
- GitHub Discussions — questions, ideas, show-and-tell
- GitHub Releases — download the explainer MP4 + release assets
If Shadow Brain makes your AI agents smarter, star the repo ⭐
MIT — see LICENSE.
Free to use, modify, fork, commercialize. Local-first by default. Works offline, in air-gapped environments, in privacy-constrained enterprises. No telemetry. No phone-home. No trial expiration.
Built by @theihtisham
.png){kind=link}
npx @theihtisham/agent-shadow-brain@latest attach-all
Topics: ai · llm · claude-code · cursor · cline · codex · copilot · hive-mind · sub-agent · sabb · causal-chains · dream-engine · reputation-ledger · swarm-debate · pre-mortem · branch-brain · attention-heatmap · token-economy · forgetting-curve · formal-verification · calibration-monitor · air-gap · e2e-encryption · hallucination-quarantine · voice-mode · brain-garden · pr-review · team-brain · brain-exchange · local-first · ollama · anthropic · openai · openrouter · gemini · deepseek · moonshot · mistral · mcp-server · model-context-protocol · lsp-server · cross-agent · multi-agent · autonomous-agents · agentic-ai · vibe-coding · cursor-ai · developer-tools · developer-productivity · coding-assistant · ai-coding · code-review · static-analysis · knowledge-graph · semantic-search · vector-embeddings · prompt-caching · json-mode · chat-with-memory · ed25519 · chacha20-poly1305 · sssp · turboquant · iclr-2026 · arxiv · zero-config · typescript · open-source · free-forever · mit-license