Skip to content
Back to search

ruvnet-brain

RuvNet Brain — a downloadable, source-grounded brain for Claude Code over Reuven Cohen's (rUv's) RuvNet stack: RuVector/RVF, Ruflo, AgentDB, RuLake, SPARC + 21 building blocks. Grounds Claude in real source via one MCP tool (search_ruvnet), so it builds with the stack instead of drifting off it.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/stuinfla/ruvnet-brain with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/stuinfla/ruvnet-brain'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stuinfla--ruvnet-brain/badge.svg)](/listings/stuinfla--ruvnet-brain)

HTML

<a href="/listings/stuinfla--ruvnet-brain"><img src="/api/listings/stuinfla--ruvnet-brain/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx ruvnet-brain

That single command runs the whole setup, narrating _what it's doing and why_ at each step: it downloads the brain from the [latest GitHub Release](https://github.com/stuinfla/ruvnet-brain/releases/latest), unpacks it to `~/.cache/ruvnet-brain/kb`, installs its local reader (no cloud calls, no API keys), and wires the Claude Code plugin — the `search_ruvnet` MCP tool + the `UserPromptSubmit` grounding hook — at user scope. The installer and the `search_ruvnet` tool run on **macOS, Linux, and Windows**; the grounding/enforcement **hooks are POSIX shell**, so they fire on macOS, Linux, and Windows-via-WSL/Git-Bash (on native Windows without WSL the search tool still works, but the auto-grounding hooks don't fire — a Node port of the hooks is on the roadmap). It's safe to re-run, and the brain itself always fetches the current Release regardless of which install path you use — you install once; you don't keep re-downloading.

> Want the bleeding-edge installer, even ahead of the last npm publish? `npx github:stuinfla/ruvnet-brain` always runs straight off the latest GitHub commit.

> **Anonymous usage counts — opt-in, counts only.** At the end of the install you're asked once: _"Share anonymous usage counts (installs/searches — never your queries or code)?"_ If you say yes, the only things ever transmitted are event counts (`install` / `search` / `session`) plus the bundle version — batched to at most one ping per machine per day. **Never** your queries, code, repo names, or paths; the entire client is one readable file (`kb/telemetry-ping.mjs`). Your answer is a plain-text file you can read or flip any time (`~/.cache/ruvnet-brain/.telemetry-consent`), and `npx ruvnet-brain --no-telemetry` declines without being asked. Found it useful? [Star the repo](https://github.com/stuinfla/ruvnet-brain) or [leave feedback in Discussions](https://github.com/stuinfla/ruvnet-brain/discussions).

<details><summary>Manual install (what the one-liner automates)</summary>

claude plugin marketplace add stuinfla/ruvnet-brain
claude plugin install ruvnet-brain@ruvnet-brain --scope user

Registers the `search_ruvnet` MCP tool, the grounding skill, and the `UserPromptSubmit` enforcement hook — globally, at user scope. The plugin expects the brain at `~/.cache/ruvnet-brain/kb` (or point `RUVNET_BRAIN_KB` at your own copy). The first install may show a one-time trust prompt for the hook.

</details> </details> </details> </details> </details> </details>

**Then just ask.** _“How does Ruflo orchestrate agent swarms, and what implements it?”_ The hook grounds the turn, Claude calls `search_ruvnet`, and it answers from cited source — down to the function body.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "ruvnet-brain",
  3. "description": "Source-grounded RuvNet Brain integrations for Claude Code and Codex.",
  4. "owner": {
  5. "name": "Stuart Kerr"
  6. },
  7. "plugins": [
  8. {
  9. "name": "ruvnet-brain",
  10. "source": "./plugin",
  11. "description": "RuvNet brain for Claude Code: source-grounded knowledge of rUv's RuvNet building blocks (RuVector, Ruflo, AgentDB, RuLake, SPARC and ~18 more) + an enforced UserPromptSubmit grounding hook so Claude answers from real source instead of drifting, and works like Ruv (assess → SPARC → ADR/DDD → QA → score → revise). Pulls in any RuvNet repo on demand."
  12. }
  13. ]
  14. }
README.md · README · 332 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. Updated: 2026-10-10 10:41:47 EDT | Version 4.6.2
  2. Created: 2026-06-29 22:36:38 EDT
  3. <div align="center">
  4. ![RuvNet Brain — the answer key for rUv's code](assets/hero.png)
  5. # 🧠 RuvNet Brain
  6. ### Discover the stack. Read the source. Build with confidence.
  7. [![RuvNet Brain version 4.6.2 — README updated 2026-10-10 EDT](https://img.shields.io/badge/version_4.7.30-updated_2026--10--10_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](plugin/.claude-plugin/plugin.json)
  8. **A source-grounded companion for Claude Code and Codex that helps you find and use Reuven Cohen's (rUv's) RuvNet ecosystem.**
  9. [![installer version](https://img.shields.io/npm/v/ruvnet-brain?label=npm&color=2e7d32&style=flat-square)](https://www.npmjs.com/package/ruvnet-brain)
  10. [![download](https://img.shields.io/badge/download-latest%20release-2e7d32?style=flat-square)](https://github.com/stuinfla/ruvnet-brain/releases/latest)
  11. [![explainer](https://img.shields.io/badge/see%20it%20visually-interactive%20explainer-e8a13a?style=flat-square)](https://isovision.ai/ruvnet-brain/)
  12. [![license](https://img.shields.io/badge/license-MIT-8ecae6?style=flat-square)](LICENSE)
  13. ### [▶ Explore the visual walkthrough](https://isovision.ai/ruvnet-brain/)
  14. [![Open the interactive RuvNet Brain explainer](assets/explainer-preview.png)](https://isovision.ai/ruvnet-brain/)
  15. <sub>Built by **Stuart Kerr** at **Isovision.ai** · open source · MIT licensed</sub>
  16. </div>
  17. The RuvNet ecosystem spans agent orchestration, vector search, memory, model routing,
  18. testing and more. Finding the right building block is often harder than writing the first
  19. line of code. Brain puts the source within reach of your coding assistant and helps it
  20. recognize capabilities you may not yet know to ask for.
  21. **Ask for the outcome you want. Brain helps connect it to the real tools and code.**
  22. > **Our north star:** useful capability discovery. A good answer should explain what helps,
  23. > why it fits, where it is implemented, and what remains unproven. Retrieval supports that
  24. > conversation; the goal is helping you build.
  25. [Get started](#get-started) · [Try it](#try-it-on-your-next-task) ·
  26. [How it works](#how-it-works) · [Capabilities](#what-brain-brings-to-your-workflow) ·
  27. [Updates](#stay-current) · [Evidence](#evidence-and-honest-limits)
  28. ## What is Brain?
  29. Brain brings three things together:
  30. - **A local knowledge bundle** built from public RuvNet source and documentation, with
  31. searchable passages, source paths, implementation bodies, symbols and capability cards.
  32. - **A coding companion** delivered through native Claude Code and Codex plugins: the
  33. `search_ruvnet` MCP tool, skills and lifecycle hooks that encourage source-grounded work.
  34. - **A local control panel**, the RuvNet Brain Console (RNBC), for inspecting your installed
  35. environment, choosing supported settings and seeing what actually ran.
  36. It gives the assistant a practical way to read the stack instead of relying on remembered
  37. APIs. You can ask by product name, describe a problem, or ask where a capability is
  38. implemented. Results identify the repository and file so the answer can be checked.
  39. **You keep control.** Recommendations, saved settings, executed tools and verified outcomes
  40. are different things. Brain's evidence surfaces are designed to show those differences.
  41. ## Get started
  42. You need Node.js **18 or newer**, npm, and a supported Claude Code or Codex installation.
  43. Run the installer from your terminal:
  44. ```bash
  45. npx ruvnet-brain@latest
  46. ```
  47. The installer downloads the signed public knowledge bundle, installs its local reader and
  48. configures the supported hosts it detects. The default Brain home is
  49. `~/.cache/ruvnet-brain`; the knowledge bundle lives in its `kb/` directory. Follow the
  50. installer's host/trust instructions and restart when it reports changed plugin declarations.
  51. Local knowledge retrieval does not require an external embedding API or its API key.
  52. Installation and updates download dependencies and release artifacts; your coding host and
  53. any optional model providers retain their own account and billing requirements.
  54. **Then ask your assistant:**
  55. ```text
  56. How does Ruflo coordinate agents? Show the source that implements it.
  57. ```
  58. Open the Console in Claude Code or Codex with **`/rnbc`** (also **`/rnb`**). It opens a local
  59. page and scans your environment. Actions explain their effect before you apply them.
  60. For an installed command, inspect the actual installation:
  61. ```bash
  62. ruvnet-brain --doctor
  63. ```
  64. If you used the one-shot installer and have no `ruvnet-brain` command on your PATH, use
  65. `npx ruvnet-brain@latest --doctor`. Keep routine updates on the installation's existing owner
  66. and path; see [stay current](#stay-current).
  67. > The installer and local search support macOS, Linux and Windows. Hook delivery and optional
  68. > executors depend on the host, OS and installed tools. Use `--doctor` and actual task receipts
  69. > to inspect your environment; a registered hook or tool alone does not establish delivery.
  70. ## Try it on your next task
  71. You do not need to know the repository names first. Start with a concrete need:
  72. - **Find a building block:** “I need persistent memory for my agents. Which RuvNet options
  73. fit, and where are their APIs implemented?”
  74. - **Understand a mechanism:** “Show me how RVF stores and queries vectors. Cite the source,
  75. and separate working implementation from design documents.”
  76. - **Plan with evidence:** “Compare the RuvNet approaches for routing model calls. Explain
  77. the tradeoffs before recommending one.”
  78. - **Improve a codebase:** “Review this project's agent workflow. Identify a useful capability
  79. we already have, then propose the smallest change and how we would verify it.”
  80. - **Build with a bounded request:** “Use `/brain-build` to add a read-only report to this app,
  81. keep existing data intact, and verify the rendered result.”
  82. - **Resume work:** “Come up to speed on this project: what changed, what is still open,
  83. and which decisions have source or test evidence?”
  84. These are starting prompts, not promises of a particular result. Ask the assistant to cite
  85. what it read, say which tools executed, and name any missing prerequisite. Optional routing
  86. requires available, authorized executors; recommendations do not automatically install tools
  87. or authorize spending.
  88. ## How it works
  89. Brain separates **building the knowledge**, **retrieving evidence**, and **acting on it**.
  90. Public source is indexed into local RVF stores. At query time, the reader combines routing
  91. and retrieval lanes, reranks candidates and returns source evidence through MCP. The coding
  92. host uses that evidence while its own tools perform the work.
  93. ![Brain architecture: public source to signed local knowledge, source retrieval, coding host and evidence](assets/diagrams/brain-architecture.svg)
  94. <details>
  95. <summary>ASCII Version (for AI/accessibility)</summary>
  96. ```text
  97. PUBLIC KNOWLEDGE YOUR LOCAL WORKFLOW
  98. RuvNet source + docs Your task in Claude Code / Codex
  99. | |
  100. v v
  101. Index source + symbols Skills + lifecycle guidance
  102. | |
  103. v v
  104. Signed public bundle ---------------> search_ruvnet (MCP)
  105. Local RVF stores + source passages Route -> retrieve -> rerank
  106. |
  107. v
  108. Source evidence: repo + path
  109. |
  110. v
  111. Host tools / authorized executors
  112. |
  113. v
  114. Changes + checks + receipts
  115. Eligible project memory (AgentDB)
  116. ```
  117. </details>
  118. The reader uses per-repository knowledge, capability cards, lexical and vector retrieval,
  119. and a shared cross-encoder ranking lane. It labels evidence and checks implementation
  120. requirements for queries that ask for code. A capability card helps find a product;
  121. it does not by itself prove an implementation exists.
  122. The public bundle contains RVF knowledge stores and source-passage sidecars. Project history
  123. is separate: eligible capture and recall use the project's canonical AgentDB store, including
  124. worktree resolution. Consent and failure reporting apply at those boundaries.
  125. **Source:** [retrieval implementation](kb/forge-ask-all.mjs),
  126. [MCP server](plugin/mcp/server.mjs), [Claude hooks](plugin/hooks/hooks.json),
  127. [Codex hooks](plugin/hooks/codex-hooks.json).
  128. ## What Brain brings to your workflow
  129. **Discover capabilities.** Ask about a need in plain language and get a starting point in the
  130. RuvNet ecosystem. Source-grounded advocacy aims to surface relevant capabilities early,
  131. with a reason they fit your task.
  132. **Read implementation.** Search results can include code bodies and source documents, with
  133. repository/path labels and evidence metadata. Evidence class matters: a design proposal and
  134. an implementation answer carry different weight.
  135. **Guide work across hosts.** The plugins share grounding and workflow skills while native
  136. hook adapters account for Claude Code and Codex differences. `/brain-prompt` helps refine a
  137. rough idea; `/brain-build` supplies a structured build contract. Configured routing can hand
  138. bounded work to supported native executors and record the choice. Routing registration is
  139. separate from observing a worker execute.
  140. **Retain useful project context.** Where an eligible project store and consent permit it,
  141. lifecycle capture records bounded, redacted observations and outcomes. Recall brings project
  142. facts and lessons back as evidence. Pending writes and incomplete restoration stay visible;
  143. inferred lessons do not silently become authoritative user instructions.
  144. **Inspect and maintain your environment.** RNBC shows installed components and supported
  145. settings. The coordinated updater uses one policy and shared owner lock for manual and
  146. scheduled runs, preserving existing managers and install paths.
  147. **Make proof part of the conversation.** Doctor, grounding receipts, update receipts and
  148. release gates distinguish a configured capability from an observed result. They help you
  149. identify the next check rather than infer success from a green registration line.
  150. ### Explore the ecosystem through Brain
  151. Ask about **Ruflo** for coordination, **RuVector / RVF** for vector knowledge,
  152. **AgentDB** for agent memory, **agentic-flow** for agent/model workflows,
  153. **Agentic QE** for quality engineering, or **SPARC** for a structured development method.
  154. Then deepen the answer with “show the implementation and prerequisites.” The bundle covers
  155. many more public repositories; its release census and source metadata define its coverage.
  156. ## From a question to reviewable work
  157. ![A source-grounded workflow: ask, discover, read, act, verify and retain evidence](assets/diagrams/brain-workflow.svg)
  158. <details>
  159. <summary>ASCII Version (for AI/accessibility)</summary>
  160. ```text
  161. ASK DISCOVER READ ACT VERIFY
  162. Your need -> Relevant -> Source -> Authorized -> Actual result
  163. capability + limits host tools + limitations
  164. ^ |
  165. | v
  166. Next task <---------------- Project evidence
  167. eligible memory
  168. ```
  169. </details>
  170. Start with the problem. Check the recommendation against its source. Make the change within
  171. the requested scope. Inspect the actual result, then retain useful evidence for the next task.
  172. The same sequence works for an explanation, a small repair or a larger delegated build.
  173. ## Stay current
  174. **4.6.0 introduces coordinated installed-tool updates.** Open RNBC and choose
  175. **Keep all tools updated**, with **Latest (recommended)** or **Alpha**. The default scope is
  176. the installed RuvNet suite; broader developer-tool maintenance is an explicit choice.
  177. Manual and scheduled runs share the coordinator, saved policy and owner lock.
  178. The schedule is **03:30 in your local time**.
  179. ```bash
  180. ruvnet-brain-update --check
  181. ruvnet-brain-update --apply
  182. ```
  183. Inspect the run receipt for what changed, failed or was excluded. A saved preference or a
  184. registered schedule establishes configuration; a completed run establishes its outcome.
  185. For an existing Brain installation, `ruvnet-brain --update` uses the update path.
  186. `ruvnet-brain --disable-nightly` disables its scheduled updates.
  187. **Code version and knowledge freshness are separate.** A code release can package the last
  188. published corpus without having refreshed every upstream repository. Public corpus production
  189. uses the protected release workflow; a consumer update downloads an available generation and
  190. does not rebuild upstream knowledge. Check `--doctor`, `SOURCE.json` and refresh receipts
  191. before treating an installation as current.
  192. The **4.6.0 published-corpus baseline** is **210 public stores · 176,584 public source chunks**.
  193. Those are bundle census values, not a claim that every upstream repository is fresh today.
  194. Later corpus publication may advance the knowledge generation independently of code changes.
  195. See [4.6.2 native update repair notes](docs/RELEASE-NOTES-4.6.2.md),
  196. [4.6.1 README/admin notes](docs/RELEASE-NOTES-4.6.1.md) and
  197. [4.6.0 coordinated-update notes](docs/RELEASE-NOTES-4.6.0.md) and the authoritative
  198. [update and release policy](CONTRIBUTING.md).
  199. ## Evidence and honest limits
  200. Brain supplies mechanisms and evidence; every claim has a boundary:
  201. - **Grounding guides the assistant.** Hooks and skills encourage source reads. Selected tool
  202. boundaries can refuse a call, but they do not guarantee the model always obeys, writes
  203. correct code or chooses the best design.
  204. - **Retrieval has a snapshot boundary.** Check dates and upstream source when currency matters.
  205. Coverage is limited to the indexed public material; the private-store fence excludes
  206. designated private stores from public bundles.
  207. - **Local search and model execution have different costs.** The reader runs locally;
  208. your host and optional provider calls may be metered. Brain does not claim automatic model
  209. switching or savings from merely registering a route.
  210. - **Memory has consent and delivery boundaries.** Queued capture is not committed history.
  211. Native delivery, exact readback and restoration require their own evidence.
  212. - **Publication is separate from source preparation.** The protected workflow binds a release
  213. to its artifact and public installation checks. A README edit, local test or passing subset
  214. does not establish a published release.
  215. <details>
  216. <summary>Recorded coverage baseline and how it is checked</summary>
  217. [![Recorded coverage baseline: 42 percent of all source; remeasure for a candidate](https://img.shields.io/badge/coverage-42%25%20of%20ALL%20source%20(recorded%20baseline)-b58900?style=flat-square)](scripts/claims-verify.mjs)
  218. This retained badge is a recorded baseline, not a new measurement from this documentation
  219. revision. `npm run test:cov` creates the coverage artifact; `npm run claims:verify` checks the
  220. advertised number against the source-bound artifact. A new release must rederive its claims.
  221. Historical routing percentages and test totals are deliberately absent from this overview:
  222. their original runs do not establish the current candidate's behavior.
  223. </details>
  224. ## For contributors
  225. The repository uses Node.js ESM. Start with [CONTRIBUTING.md](CONTRIBUTING.md), which owns
  226. release, versioning, corpus and hook policies. Install checkout dependencies and run the
  227. relevant checks:
  228. ```bash
  229. npm ci
  230. npm test
  231. npm run single-source:check
  232. npm run wired:check
  233. ```
  234. Source and integration qualification are defined by `npm run release:qualify`; use the
  235. current procedure and unique report paths in CONTRIBUTING. Claims, packed-artifact checks,
  236. public installation and native-host evidence remain separate gates.
  237. Useful places to read:
  238. - [`plugin/`](plugin/) — native plugins, skills, lifecycle hooks and MCP shell.
  239. - [`kb/`](kb/) — retrieval implementation and knowledge tooling.
  240. - [`scripts/`](scripts/) — install, update, console and release checks.
  241. - [`docs/adr/`](docs/adr/) — architecture decisions and their acceptance limits.
  242. - [`SECURITY.md`](SECURITY.md) — security boundaries and reporting.
  243. - [`explainer/`](explainer/) — source for the public visual walkthrough. The companion page
  244. is introductory; current implementation and policy are documented in this repository.
  245. ## Community and license
  246. Have a concrete example that helped, or a source-grounded failure we can reproduce?
  247. Open an [issue](https://github.com/stuinfla/ruvnet-brain/issues) or join
  248. [Discussions](https://github.com/stuinfla/ruvnet-brain/discussions).
  249. RuvNet Brain is **MIT licensed**. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.