@theihtisham/agent-shadow-brain 5.2.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. package/README.md +225 -1029
  2. package/dist/brain/agent-firewall.d.ts +7 -0
  3. package/dist/brain/agent-firewall.d.ts.map +1 -0
  4. package/dist/brain/agent-firewall.js +152 -0
  5. package/dist/brain/agent-firewall.js.map +1 -0
  6. package/dist/brain/agent-handoff.d.ts +19 -0
  7. package/dist/brain/agent-handoff.d.ts.map +1 -0
  8. package/dist/brain/agent-handoff.js +127 -0
  9. package/dist/brain/agent-handoff.js.map +1 -0
  10. package/dist/brain/air-gap.d.ts +23 -0
  11. package/dist/brain/air-gap.d.ts.map +1 -0
  12. package/dist/brain/air-gap.js +137 -0
  13. package/dist/brain/air-gap.js.map +1 -0
  14. package/dist/brain/attention-heatmap.d.ts +24 -0
  15. package/dist/brain/attention-heatmap.d.ts.map +1 -0
  16. package/dist/brain/attention-heatmap.js +108 -0
  17. package/dist/brain/attention-heatmap.js.map +1 -0
  18. package/dist/brain/auto-setup.js +19 -14
  19. package/dist/brain/auto-setup.js.map +1 -1
  20. package/dist/brain/auto-update.js +1 -1
  21. package/dist/brain/brain-chat.d.ts +42 -0
  22. package/dist/brain/brain-chat.d.ts.map +1 -0
  23. package/dist/brain/brain-chat.js +162 -0
  24. package/dist/brain/brain-chat.js.map +1 -0
  25. package/dist/brain/brain-encryption.d.ts +14 -0
  26. package/dist/brain/brain-encryption.d.ts.map +1 -0
  27. package/dist/brain/brain-encryption.js +68 -0
  28. package/dist/brain/brain-encryption.js.map +1 -0
  29. package/dist/brain/brain-exchange.d.ts +30 -0
  30. package/dist/brain/brain-exchange.d.ts.map +1 -0
  31. package/dist/brain/brain-exchange.js +106 -0
  32. package/dist/brain/brain-exchange.js.map +1 -0
  33. package/dist/brain/brain-garden.d.ts +18 -0
  34. package/dist/brain/brain-garden.d.ts.map +1 -0
  35. package/dist/brain/brain-garden.js +81 -0
  36. package/dist/brain/brain-garden.js.map +1 -0
  37. package/dist/brain/brain-portability.js +1 -1
  38. package/dist/brain/branch-brain.d.ts +23 -0
  39. package/dist/brain/branch-brain.d.ts.map +1 -0
  40. package/dist/brain/branch-brain.js +159 -0
  41. package/dist/brain/branch-brain.js.map +1 -0
  42. package/dist/brain/calibration-monitor.d.ts +20 -0
  43. package/dist/brain/calibration-monitor.d.ts.map +1 -0
  44. package/dist/brain/calibration-monitor.js +144 -0
  45. package/dist/brain/calibration-monitor.js.map +1 -0
  46. package/dist/brain/causal-chains.d.ts +37 -0
  47. package/dist/brain/causal-chains.d.ts.map +1 -0
  48. package/dist/brain/causal-chains.js +250 -0
  49. package/dist/brain/causal-chains.js.map +1 -0
  50. package/dist/brain/collision-detective.d.ts +32 -0
  51. package/dist/brain/collision-detective.d.ts.map +1 -0
  52. package/dist/brain/collision-detective.js +233 -0
  53. package/dist/brain/collision-detective.js.map +1 -0
  54. package/dist/brain/cost-aware-spawner.d.ts +7 -0
  55. package/dist/brain/cost-aware-spawner.d.ts.map +1 -0
  56. package/dist/brain/cost-aware-spawner.js +77 -0
  57. package/dist/brain/cost-aware-spawner.js.map +1 -0
  58. package/dist/brain/dream-engine.d.ts +35 -0
  59. package/dist/brain/dream-engine.d.ts.map +1 -0
  60. package/dist/brain/dream-engine.js +273 -0
  61. package/dist/brain/dream-engine.js.map +1 -0
  62. package/dist/brain/embeddings.d.ts +27 -0
  63. package/dist/brain/embeddings.d.ts.map +1 -0
  64. package/dist/brain/embeddings.js +175 -0
  65. package/dist/brain/embeddings.js.map +1 -0
  66. package/dist/brain/forgetting-curve.d.ts +21 -0
  67. package/dist/brain/forgetting-curve.d.ts.map +1 -0
  68. package/dist/brain/forgetting-curve.js +174 -0
  69. package/dist/brain/forgetting-curve.js.map +1 -0
  70. package/dist/brain/formal-verification-bridge.d.ts +26 -0
  71. package/dist/brain/formal-verification-bridge.d.ts.map +1 -0
  72. package/dist/brain/formal-verification-bridge.js +219 -0
  73. package/dist/brain/formal-verification-bridge.js.map +1 -0
  74. package/dist/brain/global-brain.d.ts +8 -1
  75. package/dist/brain/global-brain.d.ts.map +1 -1
  76. package/dist/brain/global-brain.js +24 -0
  77. package/dist/brain/global-brain.js.map +1 -1
  78. package/dist/brain/hallucination-quarantine.d.ts +26 -0
  79. package/dist/brain/hallucination-quarantine.d.ts.map +1 -0
  80. package/dist/brain/hallucination-quarantine.js +135 -0
  81. package/dist/brain/hallucination-quarantine.js.map +1 -0
  82. package/dist/brain/hive-accelerator.d.ts +39 -0
  83. package/dist/brain/hive-accelerator.d.ts.map +1 -0
  84. package/dist/brain/hive-accelerator.js +152 -0
  85. package/dist/brain/hive-accelerator.js.map +1 -0
  86. package/dist/brain/json-output.d.ts +26 -0
  87. package/dist/brain/json-output.d.ts.map +1 -0
  88. package/dist/brain/json-output.js +112 -0
  89. package/dist/brain/json-output.js.map +1 -0
  90. package/dist/brain/l0-cache.js +1 -1
  91. package/dist/brain/l0-cache.js.map +1 -1
  92. package/dist/brain/local-llm.d.ts +20 -0
  93. package/dist/brain/local-llm.d.ts.map +1 -0
  94. package/dist/brain/local-llm.js +132 -0
  95. package/dist/brain/local-llm.js.map +1 -0
  96. package/dist/brain/mcp-server.d.ts +40 -0
  97. package/dist/brain/mcp-server.d.ts.map +1 -1
  98. package/dist/brain/mcp-server.js +395 -12
  99. package/dist/brain/mcp-server.js.map +1 -1
  100. package/dist/brain/model-registry.d.ts +96 -0
  101. package/dist/brain/model-registry.d.ts.map +1 -0
  102. package/dist/brain/model-registry.js +585 -0
  103. package/dist/brain/model-registry.js.map +1 -0
  104. package/dist/brain/orchestrator.js +1 -1
  105. package/dist/brain/pr-auto-review.d.ts +17 -0
  106. package/dist/brain/pr-auto-review.d.ts.map +1 -0
  107. package/dist/brain/pr-auto-review.js +73 -0
  108. package/dist/brain/pr-auto-review.js.map +1 -0
  109. package/dist/brain/pre-mortem.d.ts +21 -0
  110. package/dist/brain/pre-mortem.d.ts.map +1 -0
  111. package/dist/brain/pre-mortem.js +210 -0
  112. package/dist/brain/pre-mortem.js.map +1 -0
  113. package/dist/brain/prompt-cache.d.ts +54 -0
  114. package/dist/brain/prompt-cache.d.ts.map +1 -0
  115. package/dist/brain/prompt-cache.js +105 -0
  116. package/dist/brain/prompt-cache.js.map +1 -0
  117. package/dist/brain/reputation-ledger.d.ts +42 -0
  118. package/dist/brain/reputation-ledger.d.ts.map +1 -0
  119. package/dist/brain/reputation-ledger.js +326 -0
  120. package/dist/brain/reputation-ledger.js.map +1 -0
  121. package/dist/brain/session-hooks.d.ts +19 -0
  122. package/dist/brain/session-hooks.d.ts.map +1 -1
  123. package/dist/brain/session-hooks.js +249 -18
  124. package/dist/brain/session-hooks.js.map +1 -1
  125. package/dist/brain/subagent-bridge.d.ts +46 -0
  126. package/dist/brain/subagent-bridge.d.ts.map +1 -0
  127. package/dist/brain/subagent-bridge.js +364 -0
  128. package/dist/brain/subagent-bridge.js.map +1 -0
  129. package/dist/brain/swarm-debate.d.ts +22 -0
  130. package/dist/brain/swarm-debate.d.ts.map +1 -0
  131. package/dist/brain/swarm-debate.js +134 -0
  132. package/dist/brain/swarm-debate.js.map +1 -0
  133. package/dist/brain/team-brain-sync.d.ts +22 -0
  134. package/dist/brain/team-brain-sync.d.ts.map +1 -0
  135. package/dist/brain/team-brain-sync.js +132 -0
  136. package/dist/brain/team-brain-sync.js.map +1 -0
  137. package/dist/brain/token-economy.d.ts +25 -0
  138. package/dist/brain/token-economy.d.ts.map +1 -0
  139. package/dist/brain/token-economy.js +216 -0
  140. package/dist/brain/token-economy.js.map +1 -0
  141. package/dist/brain/voice-mode.d.ts +15 -0
  142. package/dist/brain/voice-mode.d.ts.map +1 -0
  143. package/dist/brain/voice-mode.js +97 -0
  144. package/dist/brain/voice-mode.js.map +1 -0
  145. package/dist/cli.js +823 -4
  146. package/dist/cli.js.map +1 -1
  147. package/dist/dashboard/server.d.ts +6 -0
  148. package/dist/dashboard/server.d.ts.map +1 -1
  149. package/dist/dashboard/server.js +1118 -368
  150. package/dist/dashboard/server.js.map +1 -1
  151. package/dist/dashboard/v6-dashboard-html.d.ts +2 -0
  152. package/dist/dashboard/v6-dashboard-html.d.ts.map +1 -0
  153. package/dist/dashboard/v6-dashboard-html.js +2474 -0
  154. package/dist/dashboard/v6-dashboard-html.js.map +1 -0
  155. package/dist/index.d.ts +27 -0
  156. package/dist/index.d.ts.map +1 -1
  157. package/dist/index.js +29 -1
  158. package/dist/index.js.map +1 -1
  159. package/dist/types.d.ts +518 -2
  160. package/dist/types.d.ts.map +1 -1
  161. package/package.json +33 -4
package/README.md CHANGED
@@ -1,1159 +1,355 @@
1
1
  <div align="center">
2
2
 
3
- <img src="banner.svg" alt="Agent Shadow Brain v5.2.0 — Subconscious Singularity Edition" width="100%">
3
+ <a href="https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4">
4
+ <img src="Banner (2).png" alt="Shadow Brain v6.0 — Hive Mind · Click to watch the 2-minute explainer" width="100%">
5
+ </a>
4
6
 
5
- <br/>
7
+ ### 🎬 **[▶ Watch the 2-minute explainer](https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4)** · Click the banner above
6
8
 
7
9
  [![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)
8
10
  [![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)
9
- [![npm weekly](https://img.shields.io/npm/dw/@theihtisham/agent-shadow-brain?color=10b981&labelColor=1a0a2e&style=for-the-badge&label=weekly)](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
10
- [![bundle size](https://img.shields.io/bundlephobia/minzip/@theihtisham/agent-shadow-brain?color=f472b6&labelColor=1a0a2e&style=for-the-badge&label=size)](https://bundlephobia.com/package/@theihtisham/agent-shadow-brain)
11
- [![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)
12
- [![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?labelColor=1a0a2e&style=for-the-badge&logo=node.js)](https://nodejs.org/)
13
- [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-3178c6?labelColor=1a0a2e&style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
14
11
  [![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)
15
- [![GitHub forks](https://img.shields.io/github/forks/theihtisham/agent-shadow-brain?color=818cf8&labelColor=1a0a2e&style=for-the-badge&logo=github)](https://github.com/theihtisham/agent-shadow-brain/network)
16
- [![GitHub issues](https://img.shields.io/github/issues/theihtisham/agent-shadow-brain?color=ef4444&labelColor=1a0a2e&style=for-the-badge&logo=github)](https://github.com/theihtisham/agent-shadow-brain/issues)
17
- [![GitHub last commit](https://img.shields.io/github/last-commit/theihtisham/agent-shadow-brain?color=22d3ee&labelColor=1a0a2e&style=for-the-badge&logo=github)](https://github.com/theihtisham/agent-shadow-brain/commits)
18
- [![GitHub repo size](https://img.shields.io/github/repo-size/theihtisham/agent-shadow-brain?color=a78bfa&labelColor=1a0a2e&style=for-the-badge)](https://github.com/theihtisham/agent-shadow-brain)
19
- [![arXiv](https://img.shields.io/badge/arXiv-2504.17033-ef4444?labelColor=1a0a2e&style=for-the-badge&logo=arxiv)](https://arxiv.org/abs/2504.17033)
20
- [![ICLR 2026](https://img.shields.io/badge/ICLR-2026_TurboQuant-06b6d4?labelColor=1a0a2e&style=for-the-badge)](https://openreview.net/forum?id=TbqSEUXWaO)
21
- [![Zero Config](https://img.shields.io/badge/zero--config-auto_setup-22c55e?labelColor=1a0a2e&style=for-the-badge&logo=rocket)](#)
22
- [![MCP](https://img.shields.io/badge/MCP-19_tools-8b5cf6?labelColor=1a0a2e&style=for-the-badge&logo=anthropic)](#)
23
- [![Dashboard](https://img.shields.io/badge/dashboard-real_time-06b6d4?labelColor=1a0a2e&style=for-the-badge&logo=firefoxbrowser)](#)
24
- [![LSP](https://img.shields.io/badge/LSP-built_in-f97316?labelColor=1a0a2e&style=for-the-badge&logo=visual-studio-code)](#)
25
- [![Brain Modules](https://img.shields.io/badge/brain_modules-26-ec4899?labelColor=1a0a2e&style=for-the-badge&logo=brain)](#-architecture)
26
- [![CLI Commands](https://img.shields.io/badge/CLI-70%2B_commands-eab308?labelColor=1a0a2e&style=for-the-badge&logo=windowsterminal)](#-cli-reference)
27
- [![AI Agents](https://img.shields.io/badge/agents-10_supported-14b8a6?labelColor=1a0a2e&style=for-the-badge&logo=openai)](#)
28
- [![Singleton Brain](https://img.shields.io/badge/singleton-global_brain-a855f7?labelColor=1a0a2e&style=for-the-badge&logo=databricks)](#-1-singleton-global-brain)
29
- [![Subconscious](https://img.shields.io/badge/subconscious-proactive-ec4899?labelColor=1a0a2e&style=for-the-badge&logo=brain)](#-2-subconscious-engine)
30
- [![L0 Cache](https://img.shields.io/badge/L0_cache-%3C1ms-22d3ee?labelColor=1a0a2e&style=for-the-badge&logo=lightning)](#-4-l0-sub-millisecond-cache)
31
- [![Auto-Attach](https://img.shields.io/badge/attach--all-one_command-f59e0b?labelColor=1a0a2e&style=for-the-badge&logo=rocket)](#-3-universal-bootstrap-attach-all)
32
- [![Self Evolving](https://img.shields.io/badge/self--evolving-genetic_AI-d946ef?labelColor=1a0a2e&style=for-the-badge&logo=dna)](#)
33
- [![Infinite Memory](https://img.shields.io/badge/memory-infinite-facc15?labelColor=1a0a2e&style=for-the-badge&logo=databricks)](#)
34
- [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-22c55e?labelColor=1a0a2e&style=for-the-badge&logo=git)](https://github.com/theihtisham/agent-shadow-brain/pulls)
35
- [![Made with Love](https://img.shields.io/badge/made_with-%E2%9D%A4%EF%B8%8F-ef4444?labelColor=1a0a2e&style=for-the-badge)](#)
36
- [![Follow](https://img.shields.io/github/followers/theihtisham?label=follow&color=a855f7&labelColor=1a0a2e&style=for-the-badge&logo=github)](https://github.com/theihtisham)
12
+ [![license](https://img.shields.io/badge/license-MIT-8b5cf6?labelColor=1a0a2e&style=for-the-badge)](https://github.com/theihtisham/agent-shadow-brain/blob/main/LICENSE)
13
+ [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-3178c6?labelColor=1a0a2e&style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
14
+ [![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?labelColor=1a0a2e&style=for-the-badge&logo=node.js)](https://nodejs.org/)
15
+ [![Brain Modules](https://img.shields.io/badge/brain_modules-48-ec4899?labelColor=1a0a2e&style=for-the-badge)](#-architecture)
16
+ [![CLI Commands](https://img.shields.io/badge/CLI-90%2B_commands-eab308?labelColor=1a0a2e&style=for-the-badge&logo=windowsterminal)](#-cli-reference)
17
+ [![MCP Tools](https://img.shields.io/badge/MCP-60%2B_tools-8b5cf6?labelColor=1a0a2e&style=for-the-badge&logo=anthropic)](#-mcp-tools)
18
+ [![Tests](https://img.shields.io/badge/tests-148%2F148_passing-10b981?labelColor=1a0a2e&style=for-the-badge&logo=vitest)](#)
19
+ [![Local First](https://img.shields.io/badge/local--first-ollama_default-f97316?labelColor=1a0a2e&style=for-the-badge&logo=ollama)](#)
20
+ [![Free](https://img.shields.io/badge/price-%240_forever-22c55e?labelColor=1a0a2e&style=for-the-badge)](#)
37
21
 
38
22
  <br/>
39
23
 
40
- ### **One Brain. Every Agent. Every Project. Every Session. Forever.**
24
+ # 🧠 Shadow Brain v6.0 — Hive Mind
41
25
 
42
- **Agent Shadow Brain** is the singleton intelligence layer that makes **every AI coding agent** smarter — Claude Code, Cursor, Cline, Codex, GitHub Copilot, Windsurf, Kilo Code, Roo Code, OpenCode, Aider — all sharing the same brain. What one agent learns, every agent knows. What you discover in project A is available in project B. Forever.
26
+ ### *The first open-source brain that every AI coding agent on your machine can share.*
43
27
 
44
- > **v5.2.0 — Subconscious Singularity Edition**: One command — `npx @theihtisham/agent-shadow-brain attach-all` — auto-detects every AI agent installed on your machine and wires them to a singleton global brain. Every new session, every agent, every project: Shadow Brain proactively injects the most relevant context **before the agent asks**. Your agents stop forgetting. They stop hallucinating. They start collaborating across tools.
28
+ **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.
45
29
 
46
30
  ```bash
47
- # 30-second install. Every agent on your machine becomes smarter.
48
- npx @theihtisham/agent-shadow-brain attach-all
31
+ # 30 seconds. Every agent + sub-agent on your machine becomes smarter.
32
+ npx @theihtisham/agent-shadow-brain@latest attach-all
49
33
  ```
50
34
 
51
- [**30-Second Install**](#-getting-started-30-seconds) · [**The Singularity**](#-v520--what-makes-it-singular) · [**Live Dashboard**](#-web-dashboard) · [**Algorithms**](#-algorithms--research) · [**70+ CLI Commands**](#-cli-reference) · [**Architecture**](#-architecture) · [**Star on GitHub ⭐**](https://github.com/theihtisham/agent-shadow-brain)
35
+ **[🎬 Video](https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4) · [📦 npm](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain) · [⭐ Star on GitHub](https://github.com/theihtisham/agent-shadow-brain) · [📚 Docs](https://github.com/theihtisham/agent-shadow-brain/tree/main/docs) · [🐛 Issues](https://github.com/theihtisham/agent-shadow-brain/issues)**
52
36
 
53
37
  </div>
54
38
 
55
39
  ---
56
40
 
57
- ## ⚡ Why Shadow Brain Exists
58
-
59
- | Without Shadow Brain | With Shadow Brain |
60
- |---|---|
61
- | Every new session, your agent starts from zero | Agent gets a 2K-token briefing of relevant context **before it asks** |
62
- | Cursor learns something — Claude doesn't know | One singleton brain — what one agent learns, all agents know |
63
- | Discoveries in project A don't help project B | Cross-project memory federation by default |
64
- | Each AI tool needs its own setup | One command attaches every agent |
65
- | Agents hallucinate APIs that don't exist | Adversarial defense + multi-agent consensus voting |
66
- | Your codebase patterns are reinvented daily | Code DNA fingerprinting enforces your style across all agents |
67
- | 30 minutes of config before anything works | Zero config, auto-detect, instant value |
68
-
69
- ## 🚀 v5.2.0 — What Makes It Singular
70
-
71
- ### 🧠 1. Singleton Global Brain
72
-
73
- One database (`~/.shadow-brain/global.db`) is the **source of truth** for every project and every agent on your machine. Project-scoped views give each project its own namespace, but the data lives in one place. SQLite WAL mode + write queue handle concurrent multi-agent writes safely. Auto-vacuum at 500MB, auto-prune at 1GB.
74
-
75
- ```bash
76
- shadow-brain global stats # See cross-project, cross-agent stats
77
- shadow-brain global recall # Search across every project + every agent
78
- ```
79
-
80
- ### 💭 2. Subconscious Engine
81
-
82
- Every time any agent starts a new session, the Subconscious **proactively injects** a tight briefing of:
83
- - Recent decisions made in this project (last 24h)
84
- - Active tasks (TODOs, in-progress items)
85
- - Similar past work from other projects
86
- - Cross-agent insights (what Claude learned that Cursor should know)
87
- - Warnings and known pitfalls
88
-
89
- Hard-capped at 2K tokens. Relevance-ranked. The agent doesn't have to ask — the brain surfaces it implicitly. Like human intuition.
90
-
91
- ```bash
92
- shadow-brain subconscious inject # See what your agent gets
93
- shadow-brain subconscious configure --budget 3000 # Tune the budget
94
- ```
95
-
96
- ### 🪝 3. Universal Bootstrap (`attach-all`)
97
-
98
- One command. Detects every AI agent installed on your machine. Installs the right hook for each one's native mechanism:
99
-
100
- | Agent | Hook Mechanism |
101
- |---|---|
102
- | **Claude Code** | `~/.claude/settings.json` → `hooks.SessionStart` |
103
- | **Cursor** | `.cursor/rules/shadow-brain.md` + `.cursor/mcp.json` |
104
- | **Cline** | `~/.vscode/.../cline_mcp_settings.json` |
105
- | **Windsurf** | `.windsurfrules` + `~/.windsurf/mcp.json` |
106
- | **Codex** | `~/.codex/config.json` |
107
- | **Kilo Code** | `~/.kilocode/settings.json` |
108
- | **OpenCode** | `~/.opencode/settings.json` |
109
- | **Roo Code** | `~/.roocode/mcp.json` |
110
- | **Aider** | `~/.aider.conf.yml` `read:` directive |
111
- | **GitHub Copilot** | `.github/copilot-instructions.md` |
41
+ ## ⚡ Install in 30 seconds
112
42
 
113
43
  ```bash
114
- shadow-brain attach-all # Wire every detected agent
115
- shadow-brain attach-all --dry-run # See what would be wired
116
- ```
44
+ # Method 1 — one command, every agent wired, dashboard launches
45
+ npx @theihtisham/agent-shadow-brain@latest attach-all
117
46
 
118
- ### ⚡ 4. L0 Sub-Millisecond Cache
119
-
120
- In-memory hot tier sits in front of the singleton brain. Hot recalls return in **<1ms**. Byte-budgeted (default 64MB), LRU-evicted, per-namespace. Tracks every access in nanoseconds.
47
+ # Method 2 — global install
48
+ npm install -g @theihtisham/agent-shadow-brain
49
+ shadow-brain attach-all
50
+ shadow-brain dash . # → http://localhost:7341/
121
51
 
122
- ```bash
123
- shadow-brain global cache # Hit rate, top keys, ns-latency
52
+ # Method 3 — in a specific project only
53
+ cd my-project
54
+ npx @theihtisham/agent-shadow-brain attach-all
124
55
  ```
125
56
 
126
- ### 🎯 5. First-Class Adapters for Every Major Agent
127
-
128
- Cursor, Windsurf, and Copilot were stub aliases in v5.1.1. In v5.2.0 they each have **dedicated adapters** matching their actual file layouts, conversation parsers, and injection mechanisms.
129
-
130
- ---
57
+ **Zero config. Zero API key required. 100 % local-first.**
131
58
 
132
59
  ---
133
60
 
134
- ## The Problem
61
+ ## 🔥 Why Shadow Brain? (the 60-second pitch)
135
62
 
136
- You use AI coding agents. They're powerful, but:
137
-
138
- | Problem | Impact |
63
+ | Without Shadow Brain | With Shadow Brain v6 |
139
64
  |---|---|
140
- | Agents **forget everything** between sessions | Same mistakes, zero learning |
141
- | Multiple agents **don't communicate** | Claude doesn't know what Cursor learned |
142
- | Generated code has **hallucinations** | LLMs fabricate APIs that don't exist |
143
- | No **cross-session memory** | Every conversation starts from zero |
144
- | No **cross-project learning** | Discoveries in one project don't help others |
145
- | Setup is **complicated** | 30 minutes of config before anything works |
146
- | Each tool needs **separate config** | Claude, Cursor, Cline all need different setup |
147
-
148
- ## The Solution
149
-
150
- **Shadow Brain v5.1.1** — zero-config, auto-detecting, infinite-intelligence shadow layer:
151
-
152
- ```
153
- ┌──────────────┐ auto-detect ┌──────────────────────────────────────────┐
154
- │ AI Agents │ ◀──────────────── │ SHADOW BRAIN v5.1.1 │
155
- │ Claude Code │ MCP auto-install │ │
156
- │ Cursor │ zero-config │ ┌─ HYPER-COGNITIVE (v5.1.1 NEW) ────┐ │
157
- │ Kilo Code │ │ │ Built-in LSP Server (stdio+TCP) │ │
158
- │ Cline │ watches │ │ Custom LLM Fine-Tuning Engine │ │
159
- │ OpenCode │ ──────────────▶ │ │ Smart Cache (hot/warm/cold tiers) │ │
160
- │ Codex │ file changes │ │ Intent Engine (NLP commands) │ │
161
- │ Roo Code │ git commits │ │ Code DNA (9-gene fingerprinting) │ │
162
- │ Aider │ activity │ │ Temporal Intelligence (velocity) │ │
163
- │ Windsurf │ │ └────────────────────────────────────┘ │
164
- └──────────────┘ │ ┌─ ZERO-CONFIG (v5.0.1) ─────────────┐ │
165
- ▲ │ │ Auto-detect + MCP + Dashboard │ │
166
- │ │ │ Plugins + Export/Import + Hooks │ │
167
- │ │ └────────────────────────────────────┘ │
168
- │ │ ┌─ INFINITE MEMORY (v5.0.0) ────────┐ │
169
- │ │ │ 4-tier hierarchical compression │ │
170
- │ │ │ Context-triggered recall │ │
171
- │ │ │ Multi-agent consensus + trust │ │
172
- │ │ │ Collective cross-project learning │ │
173
- │ │ └────────────────────────────────────┘ │
174
- │ │ ┌─ HYPER-INTELLIGENCE (v4) ──────────┐ │
175
- │ │ │ TurboQuant 6x Compression │ │
176
- │ │ │ SSSP BMSSP Quantum Routing │ │
177
- │ │ │ Self-Evolution + CAIP + Swarm │ │
178
- │ │ │ PageRank + Predictive + Adversarial │ │
179
- └──────────────────────────┴──────────────────────────────────────────┘
180
- ```
65
+ | Every new session → agent starts from zero | 2K-token briefing injected **before** the first prompt |
66
+ | Cursor learns X → Claude doesn't know | **One singleton brain** every agent shares |
67
+ | Claude Task spawns sub-agent → sub-agent starts blind | **SABB** injects focused context slivers into every sub-agent |
68
+ | You can't explain *why* the AI made a choice | **Causal Memory Chains** render the full DAG of causes |
69
+ | Two agents touching the same file = merge hell | **Collision Detective** catches it in real time |
70
+ | Agents work, then go idle — wasted compute | **Dream Engine** reflects during idle, runs counterfactuals |
71
+ | No verifiable record of agent decisions | **Ed25519-signed Reputation Ledger** — tamper-proof receipts |
72
+ | Token bills explode across Opus / GPT / Gemini | **Token Economy** routes to cheapest model that passes confidence |
73
+ | Needs its own API key for everything | **Agent-proxy mode** reuses your existing Claude/Cursor/Codex config |
74
+ | Every tool runs hot, every key leaks | **Air-Gap mode** + ChaCha20 encryption at rest |
181
75
 
182
76
  ---
183
77
 
184
- ## v5.1.1 — What's New
185
-
186
- ### 6 Hyper-Cognitive Brain Modules
187
-
188
- <table>
189
- <tr>
190
- <td width="50%">
191
-
192
- ### Built-in LSP Server
193
-
194
- **Language Server Protocol** — real-time IDE feedback without external tools.
195
-
196
- Pure Node.js LSP server supporting stdio and TCP transport modes:
197
- - **Diagnostics**: pushes brain insights as IDE warnings/errors
198
- - **Hover**: shows code health info on hover
199
- - **Code Actions**: quick-fix suggestions from brain analysis
200
- - **Zero dependency**: no external LSP libraries required
201
-
202
- ```bash
203
- shadow-brain lsp --stdio # stdio mode (for editors)
204
- shadow-brain lsp --tcp 2087 # TCP mode (for remote)
205
- ```
206
-
207
- ### Custom LLM Fine-Tuning Engine
208
-
209
- **Train on your codebase** — your brain learns YOUR patterns.
210
-
211
- Automatic training data generation from code changes, insights, and fixes:
212
- - **Pair extraction**: before/after code → training pairs
213
- - **Pattern mining**: recurring fix patterns → fine-tune examples
214
- - **JSONL export**: ready for OpenAI, Anthropic, or local fine-tuning
215
- - **Quality scoring**: only high-confidence pairs enter the dataset
216
-
217
- ```bash
218
- shadow-brain fine-tune status # Training data stats
219
- shadow-brain fine-tune generate [dir] # Generate training pairs
220
- shadow-brain fine-tune export [path] # Export JSONL dataset
221
- ```
222
-
223
- </td>
224
- <td width="50%">
225
-
226
- ### Smart Cache (Multi-Tier)
227
-
228
- **Hot/Warm/Cold** — intelligent caching with predictive prefetch.
229
-
230
- Three-tier LRU cache with automatic promotion and demotion:
231
- - **Hot tier**: 200 entries, fastest access
232
- - **Warm tier**: 1000 entries, promoted on repeated access
233
- - **Cold tier**: 5000 entries, compressed storage
234
- - **Predictive prefetch**: co-access graph predicts what you'll need next
235
- - **Tag-based invalidation**: invalidate by category
236
-
237
- ```bash
238
- shadow-brain cache stats # Hit rate, tier sizes, memory usage
239
- shadow-brain cache clear # Clear all tiers
240
- ```
241
-
242
- ### Intent Engine
243
-
244
- **Natural language → brain actions** — understand what you mean.
245
-
246
- Multi-strategy NLP command understanding:
247
- - **Keyword matching**: fast path for common commands
248
- - **Fuzzy matching**: handles typos and variations
249
- - **Context-aware**: uses current file/project context
250
- - **Confidence scoring**: routes to best-matching action
251
-
252
- ```bash
253
- shadow-brain intent "find security bugs" # Maps to: analyze + security filter
254
- shadow-brain intent "show hot files" # Maps to: temporal + heatmap
255
- ```
256
-
257
- </td>
258
- </tr>
259
- <tr>
260
- <td width="50%">
261
-
262
- ### Code DNA Fingerprinting
263
-
264
- **9-gene analysis** — every file gets a unique genetic profile.
265
-
266
- Analyzes code across 9 gene categories to create a structural fingerprint:
267
- - **Structure genes**: classes, functions, nesting depth
268
- - **Complexity genes**: cyclomatic complexity, cognitive load
269
- - **Style genes**: naming conventions, formatting patterns
270
- - **Dependency genes**: import graph, coupling metrics
271
- - **Evolution genes**: change frequency, stability score
272
- - **Similarity matching**: find structurally similar files across projects
273
-
274
- ```bash
275
- shadow-brain dna analyze [dir] # Generate DNA profiles
276
- shadow-brain dna compare f1 f2 # Compare two file fingerprints
277
- shadow-brain dna similar [file] # Find similar files
278
- ```
279
-
280
- </td>
281
- <td width="50%">
282
-
283
- ### Temporal Intelligence
284
-
285
- **Time-series code evolution** — velocity tracking & bug prediction.
286
-
287
- Continuous monitoring of code change patterns over time:
288
- - **Velocity metrics**: daily/weekly/monthly rates with trend detection
289
- - **File heatmaps**: hotness scoring, churn risk, stability
290
- - **Bug prediction**: 5-factor probability model per file
291
- - **Anomaly detection**: burst detection, drought alerts, unusual hours
292
- - **Peak analysis**: identifies your most productive hours and days
293
-
294
- ```bash
295
- shadow-brain temporal stats # Velocity, anomalies, predictions
296
- shadow-brain temporal hot # Top 10 hottest files
297
- shadow-brain temporal predict # Bug risk predictions
298
- shadow-brain temporal timeline # Recent event timeline
299
- ```
300
-
301
- </td>
302
- </tr>
303
- </table>
78
+ ## 🌟 22 Novel Modules — None Exist in Any Other Tool
79
+
80
+ > *This isn't a wrapper around someone else's API. All 22 are first-party research-grade implementations, persisted to disk, with real tests.*
81
+
82
+ ### 🧠 Cognition
83
+ 1. **Sub-Agent Brain Bridge (SABB)** — sync brain context into Claude Task / Cursor Composer / CrewAI / LangGraph / AutoGen sub-agents
84
+ 2. **Causal Memory Chains** — every decision links to its causes; Graphviz DOT export
85
+ 3. **Dream Engine** — idle-time reflection: revisit / counterfactual / consolidation / contradiction / pattern-discovery
86
+ 4. **Swarm Debate Protocol** — pro / con / arbiter sub-agents for critical decisions
87
+ 5. **Pre-Mortem Assistant** — surfaces past failures from *your* project before you start
88
+ 6. **Branch Brains** — git-branch-aware memory context
89
+
90
+ ### 🔍 Transparency & Trust
91
+ 7. **Agent Reputation Ledger** — Ed25519-signed receipts, portable accuracy score
92
+ 8. **Attention Heatmap** — weighted attribution showing which memories shaped a decision
93
+ 9. **Confidence Calibration Monitor** — Brier scores + automatic trust-weighting
94
+ 10. **Formal Verification Bridge** — natural-language rules → ESLint / Semgrep / LSP diagnostics
95
+ 11. **Agent Collision Detective** — real-time overlap detection with advisory locks
96
+
97
+ ### 💰 Economy & Memory
98
+ 12. **Token Economy Engine** — cross-agent spend, savings suggestions, routing advice
99
+ 13. **Cost-Aware Sub-Agent Spawner** — auto-route trivial tasks to cheaper models
100
+ 14. **Forgetting Curve + Sleep Consolidation** — Ebbinghaus-inspired biological memory
101
+
102
+ ### 🔒 Privacy & Safety
103
+ 15. **Air-Gap Mode** — zero outbound network, localhost-only
104
+ 16. **E2E Encryption** — ChaCha20-Poly1305 at rest
105
+ 17. **Hallucination Quarantine** — isolate suspect memories, auto-expire in 7 days
106
+
107
+ ### ✨ Delight & Network Effects
108
+ 18. **Voice Mode** — natural-language intent parser for transcripts
109
+ 19. **Brain Garden** — animated visualization of memory as a living constellation
110
+ 20. **PR Auto-Review** — GitHub PR comments citing project memories
111
+ 21. **Team Brain Sync (WebRTC)** — peer-to-peer shared brain, no server
112
+ 22. **Brain Exchange** — export / import curated shareable brain slices
113
+
114
+ ### ⚡ Accelerators
115
+ - **Local-First LLM** — Ollama default; optional Anthropic / OpenAI / OpenRouter / Moonshot / Gemini / DeepSeek / Mistral
116
+ - **Hive Accelerator** — SSSP ([arXiv 2504.17033](https://arxiv.org/abs/2504.17033)) + TurboQuant ([ICLR 2026](https://openreview.net/forum?id=TbqSEUXWaO)) for fast causal traversal + 6× vector compression
304
117
 
305
118
  ---
306
119
 
307
- ## v5.0.1 — What's New
308
-
309
- ### Zero-Config Auto-Setup
310
-
311
- Install it. That's it. Shadow Brain automatically:
312
-
313
- - Detects your project type (frontend, backend, fullstack, mobile, game, systems, data-science)
314
- - Detects 25+ languages, 15+ frameworks, 5+ build tools, 5+ test frameworks
315
- - Detects which AI tools are installed (Claude Code, Cursor, Kilo Code, Cline, OpenCode, Codex, Aider, Windsurf)
316
- - Auto-installs MCP server configuration for every detected AI tool
317
- - Auto-installs git pre-commit and pre-push hooks
318
- - Generates an optimal brain config based on project complexity
319
-
320
- ```bash
321
- npm install @theihtisham/agent-shadow-brain
322
- # → Shadow Brain v5.1.1 auto-configured for my-app (fullstack)
323
- # → AI tools detected: Claude Code, Cursor
324
- # → Run: shadow-brain start
325
- ```
326
-
327
- ### MCP Server — Works with EVERY AI Tool
328
-
329
- The brain exposes itself as a **Model Context Protocol (MCP) server** with 19 tools that any AI tool can call:
330
-
331
- | MCP Tool | What It Does |
332
- |---|---|
333
- | `brain_status` | Get full brain status |
334
- | `brain_analyze` | Trigger code analysis |
335
- | `brain_health` | Get health score (A-F) |
336
- | `brain_insights` | Get recent insights |
337
- | `brain_fixes` | Get smart fix suggestions |
338
- | `brain_memory_store` | Store knowledge in hierarchical memory |
339
- | `brain_memory_search` | Search across all memory tiers |
340
- | `brain_memory_stats` | Memory compression statistics |
341
- | `brain_recall` | Context-triggered associative recall |
342
- | `brain_consensus_propose` | Submit a proposal for agent consensus |
343
- | `brain_consensus_vote` | Vote on a pending proposal |
344
- | `brain_collective_propose` | Propose a cross-project rule |
345
- | `brain_collective_search` | Search collective learning rules |
346
- | `brain_turbo_search` | Semantic search in compressed memory |
347
- | `brain_predict` | Predict bug risk for files |
348
- | `brain_graph_query` | Query knowledge graph |
349
- | `brain_defense_scan` | Scan for hallucination patterns |
350
- | `brain_evolve_status` | Get self-evolution status |
351
- | `brain_dashboard_url` | Get dashboard URL |
352
-
353
- Works with **Claude Code**, **Cursor**, **Kilo Code**, **Cline**, **OpenCode**, and any MCP-compatible AI tool.
120
+ ## 🖥️ Complete Web Control Dashboard
354
121
 
122
+ Start it:
355
123
  ```bash
356
- # Start MCP server (auto-started by AI tools)
357
- shadow-brain mcp
358
-
359
- # Cursor compatibility (root path POST + /v1/chat)
360
- # Claude Code compatibility (JSON-RPC 2.0 over stdio/HTTP)
124
+ shadow-brain dash .
125
+ # → http://localhost:7341/
361
126
  ```
362
127
 
363
- ### Rich Web Dashboard
364
-
365
- Real-time browser dashboard at `http://localhost:7341` with WebSocket live updates:
366
-
367
- - **Stats Topbar**: 8 live counters — Insights, Fixes, Memory KB, Modules, AI Tools, Evolution Gen, Swarm Convergence, Turbo Compression
368
- - **Health Score**: A-F grading with dimension breakdown (Security, Quality, Performance, Architecture, Maintainability, Test Coverage)
369
- - **Memory Tiers**: Visual bars showing Raw (50K), Summary (10K), Pattern (2K), Principle (500) with Turbo compression ratio
370
- - **Live Insights Stream**: Real-time feed of brain insights with priority badges
371
- - **Smart Fixes**: Actionable fix suggestions with file/line references
372
- - **AI Tools Panel**: 8 tools showing connected/detected status
373
- - **Brain Modules**: 13 modules with active/idle/error indicators
374
- - **Control Buttons**: Trigger analysis on-demand, refresh data
375
-
376
- ```bash
377
- shadow-brain start . # Dashboard auto-starts at http://localhost:7341
378
- shadow-brain dash . # Dashboard only mode
379
- ```
128
+ **28 tabs. Real-time data. Full control.** Every feature has live monitoring + interactive controls. Preview:
380
129
 
381
- ### Natural Language Queries
382
-
383
- Ask your brain questions in plain English:
384
-
385
- ```bash
386
- shadow-brain ask "What security issues exist in the auth module?"
387
- shadow-brain ask "Which files have the highest bug risk?"
388
- shadow-brain ask "What patterns have we learned about React hooks?"
389
- ```
130
+ | | | |
131
+ |---|---|---|
132
+ | ![Overview](docs/launch/screenshots/01-overview.png) | ![Live Graph](docs/launch/screenshots/02-graph.png) | ![Agents](docs/launch/screenshots/03-agents.png) |
133
+ | **Overview** — live counters, charts | **Live Graph** — animated signal flow | **Agents** — connect / disconnect per agent |
134
+ | ![Chat](docs/launch/screenshots/04-chat.png) | ![Memory](docs/launch/screenshots/05-memory.png) | ![SABB](docs/launch/screenshots/07-sabb.png) |
135
+ | **Chat with Brain** — RAG with citations | **Memory Browser** — semantic search | **SABB** — sliver generator + quarantine |
136
+ | ![Causal](docs/launch/screenshots/08-causal.png) | ![Dream](docs/launch/screenshots/10-dream.png) | ![Reputation](docs/launch/screenshots/11-reputation.png) |
137
+ | **Causal Chains** — traceable decisions | **Dream Engine** — reflection insights | **Reputation** — Ed25519 leaderboard |
138
+ | ![Tokens](docs/launch/screenshots/19-tokens.png) | ![Models](docs/launch/screenshots/27-models.png) | ![Command](docs/launch/screenshots/29-command-palette.png) |
139
+ | **Token Economy** — $ saved live | **Models & Intelligence** — 8 providers | **⌘K Command Palette** |
390
140
 
391
- ### Brain Export/Import — Team Sync
141
+ **→ [Browse all 29 tab screenshots](docs/launch/screenshots/)**
392
142
 
393
- Export your brain state and share it with your team:
143
+ 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.
394
144
 
395
- ```bash
396
- shadow-brain export # Full export with all modules
397
- shadow-brain export -o ./team-brain # Custom output directory
398
- shadow-brain import brain-export.json # Import + merge
399
- shadow-brain import brain-export.json --merge --skip swarm,evolution
400
- ```
401
-
402
- ### Plugin System
145
+ ---
403
146
 
404
- Extend Shadow Brain with custom plugins:
147
+ ## 🧩 Works With Every AI Coding Agent
405
148
 
406
- ```bash
407
- shadow-brain plugin list # List installed plugins
408
- shadow-brain plugin create my-plugin # Create from template
409
- shadow-brain plugin stats # Plugin system statistics
410
- ```
149
+ | Agent | Adapter | Hook target |
150
+ |---|---|---|
151
+ | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | ✅ Native | `~/.claude/settings.json` hooks.SessionStart |
152
+ | [Cursor](https://cursor.sh/) | ✅ Native | `.cursor/rules/shadow-brain.md` + MCP |
153
+ | [Cline](https://github.com/cline/cline) | ✅ Native | VS Code globalStorage MCP |
154
+ | [Codex](https://github.com/openai/codex) | ✅ Native | `~/.codex/config.json` |
155
+ | [GitHub Copilot](https://github.com/features/copilot) | ✅ Native | `.github/copilot-instructions.md` |
156
+ | [Windsurf](https://codeium.com/windsurf) | ✅ Native | `.windsurfrules` + MCP |
157
+ | [Kilo Code](https://kilocode.ai/) | ✅ Native | `~/.kilocode/settings.json` |
158
+ | [Roo Code](https://roocode.com/) | ✅ Native | `~/.roocode/mcp.json` |
159
+ | [OpenCode](https://github.com/opencode-ai/opencode) | ✅ Native | `AGENT.md` |
160
+ | [Aider](https://aider.chat/) | ✅ Native | `.aider.conf.yml` |
411
161
 
412
- Plugins can hook into `pre-analysis` and `post-analysis` pipelines to add custom insights, filter results, or integrate with external services.
162
+ **Custom agent?** Add its config path in the dashboard "Custom Agent Paths" panel — Shadow Brain will auto-read its provider + model + API key.
413
163
 
414
- ### 5 New Commands
415
-
416
- ```bash
417
- shadow-brain off # Clean shutdown
418
- shadow-brain ask "..." # Natural language query
419
- shadow-brain export # Export brain state
420
- shadow-brain import FILE # Import brain state
421
- shadow-brain plugin CMD # Plugin management
422
- ```
164
+ **Sub-agent frameworks supported by SABB:** Claude Task, Cursor Composer, Cline Sub-step, CrewAI, LangGraph, AutoGen, generic.
423
165
 
424
166
  ---
425
167
 
426
- ## Getting Started — 30 Seconds
168
+ ## 🤖 Use Your Own LLM — or Your Agent's Already-Configured One
427
169
 
428
- ```bash
429
- # Install globally
430
- npm install -g @theihtisham/agent-shadow-brain
170
+ Shadow Brain's **ModelRegistry** supports 8 providers out of the box:
431
171
 
432
- # Or use npx (no install needed)
433
- npx @theihtisham/agent-shadow-brain start .
434
- ```
172
+ **Ollama (default, local, free)** · **Anthropic Claude** · **OpenAI** · **OpenRouter** · **Moonshot / Kimi** · **Google Gemini** · **DeepSeek** · **Mistral**
435
173
 
436
- That's literally it. Shadow Brain will:
437
- 1. **Auto-detect** your project, languages, frameworks, AI tools (zero config)
438
- 2. **Auto-install** MCP server config for Claude Code, Cursor, Kilo Code, Cline, etc.
439
- 3. **Auto-install** git hooks for pre-commit and pre-push
440
- 4. Watch your project files for changes
441
- 5. Analyze every change with LLM + 22 brain modules
442
- 6. Inject expert insights into your agent's memory
443
- 7. Store all knowledge in hierarchical memory for infinite retention
444
- 8. Activate past memories automatically based on context
445
- 9. Share verified patterns across projects via collective learning
446
- 10. Compress knowledge with TurboQuant for infinite retention
447
- 11. Evolve its own rules via genetic algorithm
448
- 12. Share insights across agents via CAIP
449
- 13. Detect hallucinations with adversarial verification
450
- 14. Run consensus when multiple agents disagree
451
- 15. Serve a rich web dashboard at `localhost:7341`
452
-
453
- ### Quick Review (No Watch Mode)
174
+ 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**.
454
175
 
455
- ```bash
456
- shadow-brain review . # One-shot analysis
457
- shadow-brain review . --show-health # + health score
458
- shadow-brain review . --show-fixes # + fix suggestions
459
- shadow-brain review . --output json # JSON for scripting
460
- ```
176
+ Auto-discovery reads every agent config on your machine so you never retype a key.
461
177
 
462
178
  ---
463
179
 
464
- ## Web Dashboard
180
+ ## 📊 Real Numbers
465
181
 
466
- The v5.1.1 dashboard provides a real-time view into your brain:
467
-
468
- ```
469
- ┌──────────────────────────────────────────────────────────────────────────┐
470
- │ Shadow Brain v5.1.1 [Analyze] [↻] │
471
- ├──────────────────────────────────────────────────────────────────────────┤
472
- │ Insights: 142 │ Fixes: 38 │ Memory: 247KB │ Modules: 22/22 │ ... │
473
- ├──────────────┬─────────────────────────────────────┬───────────────────┤
474
- │ Health: 87% │ Live Insights Stream │ AI Tools │
475
- │ ████████░░ │ ● [HIGH] SQL injection in login.ts │ ● Claude Code ✓ │
476
- │ Security: A │ ● [MED] Missing error handling │ ● Cursor ✓ │
477
- │ Quality: B+ │ ● [LOW] Unused import in utils │ ● Kilo Code ✓ │
478
- │ Perf: A- │ ● [CRIT] Exposed API key │ ● Cline — │
479
- │ Arch: B │ │ ● OpenCode — │
480
- │ Maintain: A ├─────────────────────────────────────┤ ● Codex — │
481
- │ Tests: C+ │ Smart Fixes │ ● Aider — │
482
- │ │ 1. Add parameterized query... │ ● Windsurf — │
483
- ├──────────────┤ 2. Wrap in try/catch with... ├───────────────────┤
484
- │ Memory Tiers │ 3. Remove unused import on L42 │ Brain Modules │
485
- │ Raw: 8421 │ │ ● Hierarchical ✓ │
486
- │ Summ: 1203 │ │ ● TurboMemory ✓ │
487
- │ Patt: 187 │ │ ● Consensus ✓ │
488
- │ Princ: 24 │ │ ● Swarm ✓ │
489
- │ Turbo: 6.2x │ │ ● Evolution ✓ │
490
- │ │ │ ● Adversarial ✓ │
491
- └──────────────┴─────────────────────────────────────┴───────────────────┘
492
- ```
182
+ | Metric | Value |
183
+ |---|---|
184
+ | Brain modules | **48** |
185
+ | CLI commands | **90+** |
186
+ | MCP tools | **60+** |
187
+ | REST endpoints | **50+** |
188
+ | Tests passing | **148 / 148** |
189
+ | TypeScript errors | **0** |
190
+ | Supported agents | **10** (plus custom) |
191
+ | Supported LLM providers | **8** (plus agent-proxy) |
192
+ | Novel features nobody else has | **22** |
193
+ | License | **MIT** |
194
+ | Cost to run | **$0 forever** (local-first) |
493
195
 
494
196
  ---
495
197
 
496
- ## v5.0.0 Infinite Intelligence Engine
497
-
498
- ### 4 Breakthrough Modules
499
-
500
- <table>
501
- <tr>
502
- <td width="50%">
503
-
504
- ### Infinite Memory Layer
505
-
506
- **Hierarchical Memory Compression** — 4-tier pyramid that never forgets.
507
-
508
- Knowledge flows through compression tiers as it ages:
509
- - **Raw** (50K entries) — full detail, hot path
510
- - **Summary** (10K) — condensed key points
511
- - **Pattern** (2K) — recurring patterns extracted
512
- - **Principle** (500) — timeless design rules
513
-
514
- Drill-down and drill-up between tiers. Older knowledge compresses, never deletes.
515
-
516
- ```bash
517
- shadow-brain memory stats # 4 tiers | 12,847 entries
518
- shadow-brain memory store "..." # Store new knowledge
519
- shadow-brain memory search "auth" # Cross-tier semantic search
520
- ```
521
-
522
- **Context-Triggered Associative Recall** — memories that activate themselves.
523
-
524
- Instead of requiring explicit search queries, this engine monitors your current work context and automatically surfaces relevant past knowledge:
525
- - File path pattern matching (editing `auth/*.ts` → security memories)
526
- - Keyword detection (typing "database" → SQL pattern memories)
527
- - Category association (bug-fix context → past fix patterns)
528
- - Co-occurrence networks (memories activated together strengthen their link)
529
- - Learned trigger patterns that improve with use
530
-
531
- ```bash
532
- shadow-brain recall . --file src/auth/login.ts --keywords "jwt,session"
533
- # → Activates 8 memories | Top: "JWT rotation pattern (92%)"
534
- ```
535
-
536
- </td>
537
- <td width="50%">
538
-
539
- ### Multi-Agent Intelligence Layer
540
-
541
- **Consensus Engine** — voting, trust scoring, conflict resolution.
542
-
543
- When multiple AI agents observe the same codebase, they may produce conflicting insights. This engine:
544
- 1. Collects proposals from agents
545
- 2. Opens voting windows (agree/disagree/abstain with confidence)
546
- 3. Computes trust-weighted agreement scores
547
- 4. Resolves conflicts via confidence intervals
548
- 5. Tracks long-term agent trust based on proposal accuracy
198
+ ## 🚀 30-Second Quickstart
549
199
 
550
200
  ```bash
551
- shadow-brain consensus status
552
- shadow-brain consensus propose "Use bcrypt for all password hashing" security 0.95
553
- shadow-brain consensus vote <id> agree 0.9 "Industry standard"
554
- shadow-brain consensus results
555
- ```
201
+ # 1. Install
202
+ npx @theihtisham/agent-shadow-brain@latest attach-all
556
203
 
557
- **Collective Learning** — discoveries flow across all projects.
204
+ # 2. Launch the dashboard
205
+ shadow-brain dash .
206
+ # → open http://localhost:7341/
558
207
 
559
- When you discover a pattern in Project A, it becomes a verified rule available in Project B:
560
- - Rule proposal with evidence and verification
561
- - Viral propagation across connected brain instances
562
- - Accuracy tracking per rule (tested vs. false positive)
563
- - Category-based organization (security, performance, architecture...)
564
- - Trust scores for rule sources
208
+ # 3. Seed the brain (optional — populates example data)
209
+ shadow-brain reputation sign --agent claude-code --ver 4.7 --project demo \
210
+ --decision "use bcrypt cost 12 for all password hashing" \
211
+ --category security --confidence 0.92
565
212
 
566
- ```bash
567
- shadow-brain collective status
568
- shadow-brain collective propose "Always validate file upload MIME types" security
569
- shadow-brain collective search performance
213
+ # 4. Every new AI agent session automatically gets context injected
570
214
  ```
571
215
 
572
- </td>
573
- </tr>
574
- </table>
216
+ **That's it.** Open any project in Claude Code / Cursor / any supported agent — Shadow Brain is already running under the hood.
575
217
 
576
218
  ---
577
219
 
578
- ## v4.0.0 Hyper-Intelligence Engine
579
-
580
- ### 8 Breakthrough Modules (included in v5.1.1)
581
-
582
- <table>
583
- <tr>
584
- <td width="50%">
585
-
586
- ### Quantum Memory Layer
587
-
588
- **TurboQuant Infinite Memory** — never forget anything, ever.
589
-
590
- Based on Google Research's **TurboQuant** (ICLR 2026):
591
- - **PolarQuant**: 2 bits per dimension (polar coordinate quantization)
592
- - **QJL Residual**: 1 bit per dimension (random rotation + sign)
593
- - **Total**: 3 bits/dim = **6x compression** with <1% accuracy loss
594
- - **Result**: Infinite retention — old knowledge is compressed, never deleted
595
-
596
- ```bash
597
- shadow-brain turbo stats
598
- shadow-brain turbo search "authentication patterns"
599
- ```
600
-
601
- **SSSP Quantum Router** — deterministic shortest-path message routing.
602
-
603
- Based on **"Breaking the Sorting Barrier"** (arXiv 2504.17033, Duan et al.):
604
- - **BMSSP Algorithm**: O(m log<sup>2/3</sup> n) — breaks the sorting barrier
605
- - **Deterministic**: No randomization, provably correct
606
-
607
- ```bash
608
- shadow-brain route status
609
- shadow-brain route find node-A node-B
610
- ```
611
-
612
- </td>
613
- <td width="50%">
614
-
615
- ### Self-Evolution Layer
616
-
617
- **Genetic Algorithm Self-Evolution** — rules that write themselves.
618
-
619
- - **Population**: 50 genetic rule chromosomes
620
- - **Selection**: Tournament (k=5) — survival of the fittest
621
- - **Crossover**: Single-point recombination
622
- - **Mutation**: Gaussian noise (Box-Muller transform, sigma=0.1)
623
- - **Fitness**: accuracy x coverage x (1 / falsePositiveRate)
624
-
625
- ```bash
626
- shadow-brain evolve status
627
- shadow-brain evolve run
628
- shadow-brain evolve best-rules security
629
- ```
630
-
631
- **Cross-Agent Intelligence Protocol (CAIP)** — agents that talk to each other.
632
-
633
- Your Claude Code session learns what your Cursor session discovered:
634
- - Zero-config broadcast protocol
635
- - Agent identification + insight tagging
636
- - Multi-agent consensus building
637
-
638
- ```bash
639
- shadow-brain caip status
640
- shadow-brain caip broadcast "Security pattern detected"
641
- ```
220
+ ## 🧪 The Hive Mind Explainer (2 minutes)
642
221
 
643
- </td>
644
- </tr>
645
- <tr>
646
- <td width="50%">
222
+ [![Shadow Brain Hive Mind Explainer — 2 minutes](banner.svg)](https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4)
647
223
 
648
- ### Defense & Trust Layer
224
+ **[▶ Click here to watch](https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4)** · Full motion graphics explainer with voice-over walking through every feature, the live dashboard, and the 30-second install.
649
225
 
650
- **Adversarial Hallucination Defense** — trust nothing, verify everything.
226
+ Local file: `docs/launch/shadow-brain-motion-explainer-narrated.mp4` (2:05 · 1080p · narrated).
651
227
 
652
- - Cross-reference every critical insight against actual code
653
- - Evidence scoring with confidence thresholds
654
- - Verdict: `real` | `hallucinated` | `uncertain`
655
-
656
- ```bash
657
- shadow-brain defense status
658
- shadow-brain defense scan "This API endpoint exists at /api/v2/users"
659
- ```
660
-
661
- **Swarm Intelligence** — Ant Colony Optimization for file prioritization.
228
+ ---
662
229
 
663
- - Pheromone deposit: +3 for critical, +2 for high, +1 for medium
664
- - Evaporation: decay over time to avoid staleness
230
+ ## 📖 CLI Reference (top commands)
665
231
 
666
232
  ```bash
667
- shadow-brain swarm status
668
- shadow-brain swarm priorities
669
- ```
670
-
671
- </td>
672
- <td width="50%">
233
+ # Attachment + lifecycle
234
+ shadow-brain attach-all # wire every detected agent
235
+ shadow-brain detach-all # remove every hook
236
+ shadow-brain audit-hooks # list what's installed
237
+ shadow-brain dash . # launch web dashboard at :7341
238
+ shadow-brain mcp # start MCP server at :7342
673
239
 
674
- ### Analytics & Prediction Layer
240
+ # v6 Hive Mind
241
+ shadow-brain hive status # cross-module status
242
+ shadow-brain subagent sliver --parent claude-code --task "refactor auth"
243
+ shadow-brain causal trace <id> # render ancestor DAG
244
+ shadow-brain dream run # trigger idle reflection now
245
+ shadow-brain debate "Redis or Postgres?" --context "10k users"
246
+ shadow-brain premortem "migrate auth to passkeys"
247
+ shadow-brain reputation sign --agent claude-code --ver 4.7 --project X \
248
+ --decision "..." --category security --confidence 0.92
249
+ shadow-brain reputation badge claude-code --ver 4.7
675
250
 
676
- **Knowledge Graph + PageRank** — code impact radar.
251
+ # Memory + analytics
252
+ shadow-brain global recall --keywords "auth"
253
+ shadow-brain tokens report # cross-agent spend + savings
254
+ shadow-brain forget consolidate # run sleep cycle
255
+ shadow-brain formal generate "always use parameterized SQL"
256
+ shadow-brain formal export-eslint
677
257
 
678
- - Identify high-impact files (change one, break many)
679
- - Cycle detection in dependency graphs
680
- - Entity extraction with file/line tracking
258
+ # Privacy + trust
259
+ shadow-brain airgap enable --policy strict
260
+ shadow-brain encrypt file ~/.shadow-brain/global.json --passphrase ...
261
+ shadow-brain quarantine list
681
262
 
682
- ```bash
683
- shadow-brain graph build .
684
- shadow-brain graph pagerank
685
- shadow-brain graph cycles
686
- ```
263
+ # Sharing
264
+ shadow-brain exchange export --name "react-expert-v1" --tags react,auth
265
+ shadow-brain exchange import ~/brain-packs/react-expert-v1.json
687
266
 
688
- **Predictive Engine** — predict bugs before they happen.
689
-
690
- - Bug risk scoring: `low` | `medium` | `high` | `critical`
691
- - Technical debt forecasting
692
- - Anomaly detection in change patterns
693
-
694
- ```bash
695
- shadow-brain predict bugs .
267
+ # Full list
268
+ shadow-brain --help
696
269
  ```
697
270
 
698
- </td>
699
- </tr>
700
- </table>
701
-
702
271
  ---
703
272
 
704
- ## Algorithms & Research
705
-
706
- Shadow Brain v5.1.1 implements algorithms from **peer-reviewed research**:
707
-
708
- | Algorithm | Paper / Origin | Application | Complexity |
709
- |---|---|---|---|
710
- | **Hierarchical Compression** | Novel 4-tier system | Infinite memory with drill-down | O(n) per tier |
711
- | **Associative Recall** | Spreading activation model | Context-triggered memory activation | O(n x k) |
712
- | **Consensus Protocol** | Byzantine fault tolerance | Multi-agent agreement with trust | O(v x log v) |
713
- | **TurboQuant** | Google Research, ICLR 2026 | Vector compression (PolarQuant + QJL) | O(n) per vector |
714
- | **BMSSP (SSSP)** | arXiv 2504.17033, Duan et al. | Neural mesh message routing | O(m log<sup>2/3</sup> n) |
715
- | **Shannon Entropy** | Claude Shannon, 1948 | Cross-project insight relevance scoring | O(n) |
716
- | **Bayesian Inference** | Thomas Bayes, 1763 | Confidence updating, meta-learning | O(1) per update |
717
- | **Cosine Similarity** | Vector space model | Knowledge deduplication | O(d) per pair |
718
- | **PageRank** | Brin & Page, 1998 | Code entity impact analysis | O(V + E) per iteration |
719
- | **Tarjan's SCC** | Robert Tarjan, 1972 | Dependency cycle detection | O(V + E) |
720
- | **Winnowing** | Schleimer et al., 2003 | Code duplicate fingerprinting | O(n) |
721
- | **Box-Muller** | Box & Muller, 1958 | Gaussian mutation in genetic algorithm | O(1) per sample |
722
- | **Ant Colony (ACO)** | Dorigo, 1992 | File priority pheromone system | O(n x m) |
723
- | **Tournament Selection** | Goldberg, 1989 | Genetic rule selection (k=5) | O(k) per selection |
724
-
725
- ### TurboQuant Pipeline Detail
273
+ ## 🎯 Tweetable Talking Points
726
274
 
727
- ```
728
- Input Vector (64-dim, float64)
729
- |
730
- v
731
- +-------------+
732
- | PolarQuant |-- Cartesian -> Polar coordinates
733
- | 2 bits/dim |-- Quantize angles to 4 levels (2 bits each)
734
- +------+-------+ Pack into Uint8Array
735
- |
736
- v
737
- +-------------+
738
- | QJL Residual|-- Random rotation (Hadamard-like)
739
- | 1 bit/dim |-- Sign extraction (1 bit per dim)
740
- +------+-------+ Pack into Uint8Array
741
- |
742
- v
743
- TurboVector { polar: Uint8Array, qjl: Uint8Array, dim: number, radius: number }
744
- = 3 bits/dim total = 6x compression from float64
745
- = ZERO FORGETTING -- compressed knowledge stays searchable forever
746
- ```
275
+ > *"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 `npx` command. Zero API keys."*
747
276
 
748
- ---
749
-
750
- ## Features
751
-
752
- <table>
753
- <tr>
754
- <td width="20%">
755
-
756
- ### Hyper-Cognitive (v5.1.1)
757
- - Built-in LSP Server
758
- - Custom LLM Fine-Tuning
759
- - Smart Cache (3-tier)
760
- - Intent Engine (NLP)
761
- - Code DNA Fingerprinting
762
- - Temporal Intelligence
763
-
764
- </td>
765
- <td width="20%">
766
-
767
- ### Zero Config (v5.0.1)
768
- - Auto-detect project + tools
769
- - MCP for ALL AI tools
770
- - Rich web dashboard
771
- - Natural language queries
772
- - Plugin system
773
- - Brain export/import
774
- - Git hook auto-install
775
-
776
- </td>
777
- <td width="20%">
778
-
779
- ### Infinite Intelligence (v5)
780
- - 4-tier hierarchical memory
781
- - Context-triggered recall
782
- - Multi-agent consensus
783
- - Collective cross-project learning
784
-
785
- </td>
786
- <td width="20%">
787
-
788
- ### Hyper-Intelligence (v4)
789
- - TurboQuant infinite memory
790
- - SSSP quantum routing
791
- - Self-evolving genetic rules
792
- - Cross-agent protocol (CAIP)
793
- - Adversarial defense
794
- - Swarm intelligence (ACO)
795
- - Knowledge Graph + PageRank
796
- - Predictive bug forecasting
797
-
798
- </td>
799
- <td width="20%">
800
-
801
- ### Developer Experience
802
- - **60+ CLI commands**
803
- - MCP Server (19 tools)
804
- - Built-in LSP Server
805
- - Web dashboard (real-time)
806
- - Terminal UI (Ink/React)
807
- - Pre-commit hooks
808
- - GitHub Actions CI
809
- - Plugin architecture
810
-
811
- </td>
812
- </tr>
813
- </table>
814
-
815
- ---
277
+ > *"Every AI decision Shadow Brain makes is Ed25519-signed. Every cause is traced. Every collision is caught before it happens. Free forever."*
816
278
 
817
- ## Architecture
818
-
819
- ### v5.1.1 Module Map (22 modules)
820
-
821
- | Module | File | What It Does | Since |
822
- |---|---|---|---|
823
- | **LSP Server** | `brain/lsp-server.ts` | Built-in Language Server Protocol (stdio+TCP) | v5.1.1 |
824
- | **Fine-Tuning Engine** | `brain/fine-tuning-engine.ts` | Custom LLM training data generation | v5.1.1 |
825
- | **Smart Cache** | `brain/smart-cache.ts` | Multi-tier caching with predictive prefetch | v5.1.1 |
826
- | **Intent Engine** | `brain/intent-engine.ts` | Natural language command understanding | v5.1.1 |
827
- | **Code DNA** | `brain/code-dna.ts` | 9-gene code fingerprinting + similarity | v5.1.1 |
828
- | **Temporal Intelligence** | `brain/temporal-intelligence.ts` | Velocity tracking, heatmaps, bug prediction | v5.1.1 |
829
- | **Auto Setup** | `brain/auto-setup.ts` | Zero-config project + tool detection | v5.0.1 |
830
- | **MCP Server** | `brain/mcp-server.ts` | 19-tool MCP server for all AI tools | v5.0.1 |
831
- | **Plugin System** | `brain/plugin-system.ts` | Hookable analysis pipeline | v5.0.1 |
832
- | **Brain Portability** | `brain/brain-portability.ts` | Export/import brain state | v5.0.1 |
833
- | **Dashboard** | `dashboard/server.ts` | Real-time WebSocket dashboard | v5.0.1 |
834
- | **Hierarchical Memory** | `brain/hierarchical-memory.ts` | 4-tier infinite memory | v5.0.0 |
835
- | **Context Recall** | `brain/context-recall.ts` | Associative memory activation | v5.0.0 |
836
- | **Consensus Engine** | `brain/consensus-engine.ts` | Multi-agent voting + trust | v5.0.0 |
837
- | **Collective Learning** | `brain/collective-learning.ts` | Cross-project rule sharing | v5.0.0 |
838
- | **TurboMemory** | `brain/turbo-memory.ts` | 6x compressed infinite memory | v4.0.0 |
839
- | **SSSP Router** | `brain/sssp-router.ts` | Sub-sorting routing | v4.0.0 |
840
- | **Self-Evolution** | `brain/self-evolution.ts` | Genetic rule optimization | v4.0.0 |
841
- | **Cross-Agent** | `brain/cross-agent-protocol.ts` | Multi-agent broadcast | v4.0.0 |
842
- | **Adversarial** | `brain/adversarial-defense.ts` | Hallucination detection | v4.0.0 |
843
- | **Swarm** | `brain/swarm-intelligence.ts` | File priority pheromones | v4.0.0 |
844
- | **Knowledge Graph** | `brain/knowledge-graph.ts` | PageRank impact analysis | v4.0.0 |
845
- | **Predictive** | `brain/predictive-engine.ts` | Bug risk & debt forecasting | v4.0.0 |
279
+ > *"22 novel features nobody else has. Free. Open source. Local-first. `npx @theihtisham/agent-shadow-brain`."*
846
280
 
847
281
  ---
848
282
 
849
- ## CLI Reference
283
+ ## 🛠️ For Contributors
850
284
 
851
- ### Core Commands
852
-
853
- | Command | Description |
854
- |---|---|
855
- | `shadow-brain start [dir]` | Start real-time watching + dashboard + MCP |
856
- | `shadow-brain off` | Clean shutdown |
857
- | `shadow-brain review [dir]` | One-shot code analysis |
858
- | `shadow-brain health [dir]` | Health score (A-F grading) |
859
- | `shadow-brain fix [dir]` | Smart fix suggestions |
860
- | `shadow-brain report [dir]` | HTML/MD/JSON reports |
861
- | `shadow-brain metrics [dir]` | Code metrics |
862
- | `shadow-brain scan [dir]` | Vulnerability scanner |
863
- | `shadow-brain pr [dir]` | Generate PR description |
864
- | `shadow-brain commit-msg [dir]` | Generate commit message |
865
- | `shadow-brain ci [dir]` | GitHub Actions workflow |
866
- | `shadow-brain hook [dir]` | Pre-commit hook |
867
- | `shadow-brain dash [dir]` | Web dashboard |
868
- | `shadow-brain mcp` | MCP server mode |
869
- | `shadow-brain inject <msg>` | Inject into agent memory |
870
- | `shadow-brain status` | Current configuration |
871
- | `shadow-brain setup` | Interactive setup wizard |
872
- | `shadow-brain doctor` | Health check & diagnostics |
873
- | `shadow-brain ask <question>` | Natural language brain query |
874
-
875
- ### v5.1.1 Hyper-Cognitive Commands (NEW)
876
-
877
- | Command | Description |
878
- |---|---|
879
- | `shadow-brain lsp [--stdio\|--tcp PORT]` | Start built-in LSP server |
880
- | `shadow-brain fine-tune status` | Fine-tuning training data stats |
881
- | `shadow-brain fine-tune generate [dir]` | Generate training pairs from code |
882
- | `shadow-brain fine-tune export [path]` | Export JSONL dataset for fine-tuning |
883
- | `shadow-brain cache stats` | Smart cache hit rate, tier sizes, memory |
884
- | `shadow-brain cache clear` | Clear all cache tiers |
885
- | `shadow-brain intent <text>` | Parse natural language intent |
886
- | `shadow-brain dna analyze [dir]` | Generate Code DNA profiles |
887
- | `shadow-brain dna compare <f1> <f2>` | Compare two file fingerprints |
888
- | `shadow-brain dna similar <file>` | Find structurally similar files |
889
- | `shadow-brain temporal stats` | Velocity, anomalies, predictions |
890
- | `shadow-brain temporal hot` | Top 10 hottest files by churn |
891
- | `shadow-brain temporal predict` | Bug risk predictions |
892
- | `shadow-brain temporal timeline` | Recent event timeline |
893
-
894
- ### v5.0.1 Commands
895
-
896
- | Command | Description |
897
- |---|---|
898
- | `shadow-brain off` | Clean shutdown of all brain processes |
899
- | `shadow-brain ask <question>` | Natural language query to the brain |
900
- | `shadow-brain export [-o dir]` | Export full brain state to JSON |
901
- | `shadow-brain import <file> [--merge]` | Import brain state |
902
- | `shadow-brain plugin list` | List installed plugins |
903
- | `shadow-brain plugin create <name>` | Create plugin from template |
904
- | `shadow-brain plugin stats` | Plugin system statistics |
905
-
906
- ### v5.0.0 Infinite Intelligence Commands
285
+ ```bash
286
+ git clone https://github.com/theihtisham/agent-shadow-brain.git
287
+ cd agent-shadow-brain
288
+ npm install
289
+ npm run build
290
+ npm test # 148/148 tests
291
+ npm run dev # ts-node dev mode
907
292
 
908
- | Command | Description |
909
- |---|---|
910
- | `shadow-brain memory stats` | 4-tier hierarchical memory stats |
911
- | `shadow-brain memory store <text>` | Store knowledge at raw tier |
912
- | `shadow-brain memory search <query>` | Cross-tier semantic search |
913
- | `shadow-brain recall . --file <f>` | Context-triggered associative recall |
914
- | `shadow-brain consensus status` | Multi-agent consensus stats |
915
- | `shadow-brain consensus propose <text> <cat> <conf>` | Submit proposal for voting |
916
- | `shadow-brain consensus vote <id> <vote> <conf> <reason>` | Vote on a proposal |
917
- | `shadow-brain consensus results` | All resolved proposals |
918
- | `shadow-brain collective status` | Cross-project rule stats |
919
- | `shadow-brain collective propose <text> <cat>` | Propose a collective rule |
920
- | `shadow-brain collective search <cat>` | Search collective rules by category |
921
- | `shadow-brain v5 [dir]` | Run ALL v5.0.0 analyses |
922
-
923
- ### v4.0.0 Hyper-Intelligence Commands
924
-
925
- | Command | Description |
926
- |---|---|
927
- | `shadow-brain turbo stats` | TurboQuant infinite memory stats |
928
- | `shadow-brain turbo search <q>` | Semantic search compressed memory |
929
- | `shadow-brain route status` | SSSP routing status |
930
- | `shadow-brain route find <from> <to>` | Shortest path query |
931
- | `shadow-brain caip status` | Cross-agent protocol status |
932
- | `shadow-brain caip broadcast <msg>` | Broadcast to all agents |
933
- | `shadow-brain evolve status` | Genetic algorithm generation stats |
934
- | `shadow-brain evolve run` | Trigger evolution cycle |
935
- | `shadow-brain evolve best-rules [cat]` | Top evolved rules by category |
936
- | `shadow-brain predict bugs [dir]` | Bug risk prediction |
937
- | `shadow-brain graph build [dir]` | Build knowledge graph + PageRank |
938
- | `shadow-brain swarm status` | Swarm convergence + priorities |
939
- | `shadow-brain swarm priorities` | File hotspot ranking |
940
- | `shadow-brain defense status` | Adversarial defense statistics |
941
- | `shadow-brain defense scan <text>` | Scan text for hallucination patterns |
942
- | `shadow-brain v4 [dir]` | Run ALL v4.0.0 analyses |
293
+ # Rebuild the explainer video
294
+ node tools/record-motion-explainer.mjs
943
295
 
944
- ---
296
+ # Capture fresh dashboard screenshots
297
+ node tools/capture-screenshots.mjs
945
298
 
946
- ## Programmatic API
947
-
948
- ```typescript
949
- import {
950
- Orchestrator,
951
- // v5.1.1 — Hyper-Cognitive modules
952
- LSPServer,
953
- FineTuningEngine,
954
- SmartCache,
955
- IntentEngine,
956
- CodeDNA,
957
- TemporalIntelligence,
958
- // v5.0.1 — Zero-Config modules
959
- AutoSetup,
960
- PluginSystem,
961
- BrainPortability,
962
- // v5.0.0 — Infinite Intelligence modules
963
- HierarchicalMemory,
964
- ContextRecall,
965
- ConsensusEngine,
966
- CollectiveLearning,
967
- // v4.0.0 — Hyper-Intelligence modules
968
- TurboMemory,
969
- SSSPRouter,
970
- SelfEvolution,
971
- CrossAgentProtocol,
972
- AdversarialDefense,
973
- SwarmIntelligence,
974
- KnowledgeGraph,
975
- PredictiveEngine,
976
- NeuralMesh,
977
- } from '@theihtisham/agent-shadow-brain';
978
-
979
- // v5.1.1 — Built-in LSP server
980
- const lsp = new LSPServer('./my-project');
981
- lsp.start({ mode: 'tcp', port: 2087 }); // or { mode: 'stdio' }
982
-
983
- // v5.1.1 — Smart Cache
984
- const cache = new SmartCache({ maxHotEntries: 200, enablePrefetch: true });
985
- cache.set('analysis:auth', analysisResult, { ttl: 300_000, tags: ['security'] });
986
- const cached = cache.get('analysis:auth');
987
-
988
- // v5.1.1 — Temporal Intelligence
989
- const temporal = new TemporalIntelligence('./my-project');
990
- temporal.recordCommit(['src/auth.ts'], 'fix: JWT rotation');
991
- const velocity = temporal.getVelocity(); // { daily, weekly, trend: 'accelerating' }
992
- const bugRisks = temporal.predictBugs(10);
993
-
994
- // v5.1.1 — Code DNA
995
- const dna = new CodeDNA('./my-project');
996
- const profile = await dna.analyze('src/auth.ts');
997
- const similar = await dna.findSimilar('src/auth.ts', 5);
998
-
999
- // v5.0.1 — Zero-config auto-setup
1000
- const setup = new AutoSetup('./my-project');
1001
- const config = await setup.detect();
1002
- // → { projectType: 'fullstack', languages: ['typescript','python'], frameworks: ['next.js'], aiTools: [...] }
1003
- await setup.installMCPForTools(['Claude Code', 'Cursor']);
1004
- await setup.installGitHooks();
1005
-
1006
- // Create the brain
1007
- const brain = new Orchestrator({
1008
- provider: 'anthropic',
1009
- projectDir: './my-project',
1010
- agents: ['claude-code', 'cursor', 'cline'],
1011
- watchMode: true,
1012
- autoInject: true,
1013
- brainPersonality: 'balanced',
1014
- });
1015
-
1016
- // v5.0.1 — Plugin system
1017
- const plugins = new PluginSystem('./my-project');
1018
- await plugins.loadAll();
1019
- await plugins.preAnalysis({ files: ['src/auth.ts'], projectDir: './my-project' });
1020
-
1021
- // v5.0.1 — Brain portability
1022
- const porter = new BrainPortability('./my-project');
1023
- const { filePath, sizeBytes, checksum } = await porter.exportBrain();
1024
-
1025
- // v5.0.0 — Infinite Intelligence
1026
- const hmem = new HierarchicalMemory();
1027
- await hmem.store('JWT rotation pattern: rotate every 24h with refresh tokens', 'security', 0.9);
1028
- const results = hmem.search('jwt');
1029
-
1030
- const recall = new ContextRecall(hmem);
1031
- const activated = recall.recall({
1032
- currentFile: 'src/auth/login.ts',
1033
- currentCategory: 'security',
1034
- recentEdits: ['src/auth/login.ts', 'src/middleware/auth.ts'],
1035
- projectType: 'node',
1036
- keywords: ['jwt', 'authentication', 'session'],
1037
- });
1038
-
1039
- const consensus = new ConsensusEngine('my-agent');
1040
- const proposalId = consensus.propose('Use bcrypt cost factor 12', 'security', 0.95);
1041
-
1042
- // Start everything
1043
- await brain.start();
299
+ # Seed the brain with demo data
300
+ node tools/seed-brain.mjs
1044
301
  ```
1045
302
 
1046
- ---
1047
-
1048
- ## Health Score System
1049
-
1050
- | Dimension | Weight | Checks |
1051
- |---|---|---|
1052
- | Security | 25% | Vulnerabilities, secrets, exposed keys |
1053
- | Quality | 25% | Code smells, anti-patterns, complexity |
1054
- | Performance | 15% | N+1 queries, memory leaks, blocking ops |
1055
- | Architecture | 15% | Coupling, cohesion, dependencies |
1056
- | Maintainability | 10% | Duplication, file sizes, comments |
1057
- | Test Coverage | 10% | Test presence, assertion quality |
303
+ Issues, PRs, discussions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
1058
304
 
1059
305
  ---
1060
306
 
1061
- ## Version History
307
+ ## 📚 Documentation
1062
308
 
1063
- > **Full changelogs, migration guides, and detailed release notes:** [`docs/versions/`](docs/versions/)
1064
- >
1065
- > **Compact changelog:** [`CHANGELOG.md`](CHANGELOG.md)
1066
-
1067
- | Version | Codename | Date | Highlights |
1068
- |---|---|---|---|
1069
- | **[v5.1.1](docs/versions/v5.1.1.md)** | Hyper-Cognitive | 2026-04-18 | LSP Server, Fine-Tuning Engine, Smart Cache, Intent Engine, Code DNA, Temporal Intelligence |
1070
- | **[v5.0.1](docs/versions/v5.0.1.md)** | Zero-Config | 2026-04-15 | Auto-Setup, MCP Server (19 tools), Dashboard, NLP Queries, Plugin System |
1071
- | **[v5.0.0](docs/versions/v5.0.0.md)** | Infinite Intelligence | 2026-04-12 | Hierarchical Memory, Associative Recall, Multi-Agent Consensus, Collective Learning |
1072
- | **[v4.0.0](docs/versions/v4.0.0.md)** | Hyper-Intelligence | 2026-04-08 | TurboQuant, SSSP Routing, Self-Evolution, CAIP, Adversarial Defense, Swarm, Knowledge Graph |
1073
- | **[v3.0.0](docs/versions/v3.0.0.md)** | Hyper-Intelligence | 2026-04-01 | Cognitive Load Analysis, Security Audit Engine, Influence Map |
1074
- | **[v2.1.0](docs/versions/v2.1.0.md)** | Quantum Neural Mesh | 2026-03-25 | Shannon Entropy, Cosine Similarity, Bayesian Confidence |
1075
- | **[v2.0.0](docs/versions/v2.0.0.md)** | Super-Intelligence | 2026-03-18 | Semantic Analyzer, Dependency Graph, Code Similarity, MCP Server |
1076
- | **[v1.0.0](docs/versions/v1.0.0.md)** | Foundation | 2026-02-28 | 7 Agent Adapters, Health Scoring, Smart Fixes, Vulnerability Scanning |
309
+ - **[CHANGELOG.md](CHANGELOG.md)** — release notes
310
+ - **[docs/versions/v6.0.0.md](docs/versions/v6.0.0.md)** — v6 release details
311
+ - **[docs/launch/HIVEMIND_VIDEO.md](docs/launch/HIVEMIND_VIDEO.md)** — video production pipeline
312
+ - **[docs/launch/screenshots/](docs/launch/screenshots/)** — all 29 dashboard screenshots
313
+ - **[SECURITY.md](SECURITY.md)** — security policy
314
+ - **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — community guidelines
1077
315
 
1078
316
  ---
1079
317
 
1080
- ## Supported Agents & Tools
1081
-
1082
- | Agent | Status | MCP Support | Injection Target |
1083
- |---|---|---|---|
1084
- | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Full Support | Auto-install | `CLAUDE.md`, `.claude/` |
1085
- | [Cursor](https://cursor.sh/) | Full Support | Auto-install | `.cursor/mcp.json` |
1086
- | [Kilo Code](https://kilocode.ai/) | Full Support | Auto-install | `.kilocode/rules.md` |
1087
- | [Cline](https://github.com/cline/cline) | Full Support | Auto-install | `.clinerules` |
1088
- | [OpenCode](https://github.com/opencode-ai/opencode) | Full Support | Yes | `AGENT.md` |
1089
- | [Codex](https://github.com/openai/codex) | Full Support | Yes | `AGENTS.md` |
1090
- | [Roo Code](https://roocode.com/) | Full Support | Yes | `.roo/rules.md` |
1091
- | [Aider](https://aider.chat/) | Full Support | Yes | `.aider.conf.yml` |
1092
- | [Windsurf](https://codeium.com/windsurf) | Detection | Yes | `.windsurfrules` |
318
+ ## 💬 Community
1093
319
 
1094
- ---
320
+ - **[GitHub Issues](https://github.com/theihtisham/agent-shadow-brain/issues)** — bug reports, feature requests
321
+ - **[GitHub Discussions](https://github.com/theihtisham/agent-shadow-brain/discussions)** — questions, ideas, show-and-tell
322
+ - **[GitHub Releases](https://github.com/theihtisham/agent-shadow-brain/releases)** — download the explainer MP4 + release assets
1095
323
 
1096
- ## Development
1097
-
1098
- ```bash
1099
- git clone https://github.com/theihtisham/agent-shadow-brain.git
1100
- cd agent-shadow-brain
1101
- npm install
1102
- npm run build
1103
- npm test
1104
- ```
324
+ **If Shadow Brain makes your AI agents smarter, star the repo ⭐**
1105
325
 
1106
326
  ---
1107
327
 
1108
- ## Roadmap
1109
-
1110
- - [x] ~~MCP Server, multi-project, team mode~~ (v2.0)
1111
- - [x] ~~Cross-session neural mesh~~ (v2.1)
1112
- - [x] ~~TurboQuant infinite memory~~ (v4.0)
1113
- - [x] ~~SSSP quantum routing~~ (v4.0)
1114
- - [x] ~~Self-evolving rules~~ (v4.0)
1115
- - [x] ~~Cross-agent protocol~~ (v4.0)
1116
- - [x] ~~Adversarial hallucination defense~~ (v4.0)
1117
- - [x] ~~Hierarchical memory compression~~ (v5.0)
1118
- - [x] ~~Context-triggered associative recall~~ (v5.0)
1119
- - [x] ~~Multi-agent consensus protocol~~ (v5.0)
1120
- - [x] ~~Collective cross-project learning~~ (v5.0)
1121
- - [x] ~~Zero-config auto-setup~~ (v5.0.1)
1122
- - [x] ~~MCP server for Cursor + all tools~~ (v5.0.1)
1123
- - [x] ~~Rich web dashboard with real-time WebSocket~~ (v5.0.1)
1124
- - [x] ~~Plugin system + brain export/import~~ (v5.0.1)
1125
- - [x] ~~Custom LLM fine-tuning~~ (v5.1.1)
1126
- - [x] ~~Language server (LSP)~~ (v5.1.1)
1127
- - [x] ~~Web dashboard v3~~ (v5.1.1)
1128
- - [ ] **Visual Studio Code integration** — inline insight overlays
1129
- - [ ] **Multi-model orchestration** — route insights through multiple LLMs
1130
- - [ ] **Real-time collaboration** — team brain with live cursors
328
+ ## ⭐ Stargazers Over Time
1131
329
 
1132
- ---
1133
-
1134
- ## License
1135
-
1136
- MIT License — see [LICENSE](LICENSE) for details.
330
+ [![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)
1137
331
 
1138
332
  ---
1139
333
 
1140
- ## Author
334
+ ## 📜 License
1141
335
 
1142
- **theihtisham**
336
+ **MIT** — see [LICENSE](LICENSE).
1143
337
 
1144
- [![GitHub](https://img.shields.io/badge/GitHub-theihtisham-181717?style=flat-square&logo=github)](https://github.com/theihtisham)
1145
- [![npm](https://img.shields.io/badge/npm-@theihtisham-CB3837?style=flat-square&logo=npm)](https://www.npmjs.com/~theihtisham)
338
+ 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.
1146
339
 
1147
340
  ---
1148
341
 
1149
342
  <div align="center">
1150
343
 
1151
- ### If Shadow Brain makes your AI agents smarter, give it a star
344
+ ### Built by [@theihtisham](https://github.com/theihtisham)
1152
345
 
1153
- [![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)
346
+ <a href="https://github.com/theihtisham"><img src="https://img.shields.io/badge/GitHub-theihtisham-181717?style=for-the-badge&logo=github" alt="GitHub"></a>
347
+ <a href="https://www.npmjs.com/~theihtisham"><img src="https://img.shields.io/badge/npm-@theihtisham-CB3837?style=for-the-badge&logo=npm" alt="npm"></a>
348
+
349
+ ### The Hive Mind for every AI coding agent on your machine.
1154
350
 
1155
- **Built with brains by [theihtisham](https://github.com/theihtisham)**
351
+ **`npx @theihtisham/agent-shadow-brain@latest attach-all`**
1156
352
 
1157
- **Topics:** `ai` `artificial-intelligence` `llm` `claude-code` `cursor` `cline` `kilo-code` `codex` `roo-code` `aider` `opencode` `windsurf` `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` `neural-mesh` `quantum-computing` `shannon-entropy` `bayesian-inference` `mcp-server` `model-context-protocol` `semantic-analysis` `dependency-graph` `turboquant` `sssp-algorithm` `genetic-algorithm` `swarm-intelligence` `pagerank` `knowledge-graph` `hallucination-detection` `cross-agent` `self-evolving` `predictive-engine` `ant-colony` `infinite-memory` `vector-compression` `iclr-2026` `arxiv` `super-intelligence` `hyper-intelligence` `autonomous-agents` `ai-engineering` `agentic-coding` `vibe-coding` `cursor-ai` `zero-config` `auto-setup` `dashboard` `plugin-system` `brain-export` `natural-language` `real-time` `websocket` `team-collaboration` `ci-cd` `open-source` `trending` `hierarchical-memory` `context-recall` `consensus-engine` `collective-learning` `infinite-intelligence` `coding-assistant` `lsp-server` `language-server-protocol` `fine-tuning` `smart-cache` `intent-engine` `code-dna` `temporal-intelligence` `hyper-cognitive`
353
+ <sub>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`</sub>
1158
354
 
1159
355
  </div>