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.
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
Markdown
[](/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
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.
- {
- "name": "ruvnet-brain",
- "description": "Source-grounded RuvNet Brain integrations for Claude Code and Codex.",
- "owner": {
- "name": "Stuart Kerr"
- },
- "plugins": [
- {
- "name": "ruvnet-brain",
- "source": "./plugin",
- "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."
- }
- ]
- }
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.
- Updated: 2026-10-10 10:41:47 EDT | Version 4.6.2
- Created: 2026-06-29 22:36:38 EDT
- <div align="center">
- 
- # 🧠 RuvNet Brain
- ### Discover the stack. Read the source. Build with confidence.
- [](plugin/.claude-plugin/plugin.json)
- **A source-grounded companion for Claude Code and Codex that helps you find and use Reuven Cohen's (rUv's) RuvNet ecosystem.**
- [](https://www.npmjs.com/package/ruvnet-brain)
- [](https://github.com/stuinfla/ruvnet-brain/releases/latest)
- [](https://isovision.ai/ruvnet-brain/)
- [](LICENSE)
- ### [▶ Explore the visual walkthrough](https://isovision.ai/ruvnet-brain/)
- [](https://isovision.ai/ruvnet-brain/)
- <sub>Built by **Stuart Kerr** at **Isovision.ai** · open source · MIT licensed</sub>
- </div>
- The RuvNet ecosystem spans agent orchestration, vector search, memory, model routing,
- testing and more. Finding the right building block is often harder than writing the first
- line of code. Brain puts the source within reach of your coding assistant and helps it
- recognize capabilities you may not yet know to ask for.
- **Ask for the outcome you want. Brain helps connect it to the real tools and code.**
- > **Our north star:** useful capability discovery. A good answer should explain what helps,
- > why it fits, where it is implemented, and what remains unproven. Retrieval supports that
- > conversation; the goal is helping you build.
- [Get started](#get-started) · [Try it](#try-it-on-your-next-task) ·
- [How it works](#how-it-works) · [Capabilities](#what-brain-brings-to-your-workflow) ·
- [Updates](#stay-current) · [Evidence](#evidence-and-honest-limits)
- ## What is Brain?
- Brain brings three things together:
- - **A local knowledge bundle** built from public RuvNet source and documentation, with
- searchable passages, source paths, implementation bodies, symbols and capability cards.
- - **A coding companion** delivered through native Claude Code and Codex plugins: the
- `search_ruvnet` MCP tool, skills and lifecycle hooks that encourage source-grounded work.
- - **A local control panel**, the RuvNet Brain Console (RNBC), for inspecting your installed
- environment, choosing supported settings and seeing what actually ran.
- It gives the assistant a practical way to read the stack instead of relying on remembered
- APIs. You can ask by product name, describe a problem, or ask where a capability is
- implemented. Results identify the repository and file so the answer can be checked.
- **You keep control.** Recommendations, saved settings, executed tools and verified outcomes
- are different things. Brain's evidence surfaces are designed to show those differences.
- ## Get started
- You need Node.js **18 or newer**, npm, and a supported Claude Code or Codex installation.
- Run the installer from your terminal:
- ```bash
- npx ruvnet-brain@latest
- ```
- The installer downloads the signed public knowledge bundle, installs its local reader and
- configures the supported hosts it detects. The default Brain home is
- `~/.cache/ruvnet-brain`; the knowledge bundle lives in its `kb/` directory. Follow the
- installer's host/trust instructions and restart when it reports changed plugin declarations.
- Local knowledge retrieval does not require an external embedding API or its API key.
- Installation and updates download dependencies and release artifacts; your coding host and
- any optional model providers retain their own account and billing requirements.
- **Then ask your assistant:**
- ```text
- How does Ruflo coordinate agents? Show the source that implements it.
- ```
- Open the Console in Claude Code or Codex with **`/rnbc`** (also **`/rnb`**). It opens a local
- page and scans your environment. Actions explain their effect before you apply them.
- For an installed command, inspect the actual installation:
- ```bash
- ruvnet-brain --doctor
- ```
- If you used the one-shot installer and have no `ruvnet-brain` command on your PATH, use
- `npx ruvnet-brain@latest --doctor`. Keep routine updates on the installation's existing owner
- and path; see [stay current](#stay-current).
- > The installer and local search support macOS, Linux and Windows. Hook delivery and optional
- > executors depend on the host, OS and installed tools. Use `--doctor` and actual task receipts
- > to inspect your environment; a registered hook or tool alone does not establish delivery.
- ## Try it on your next task
- You do not need to know the repository names first. Start with a concrete need:
- - **Find a building block:** “I need persistent memory for my agents. Which RuvNet options
- fit, and where are their APIs implemented?”
- - **Understand a mechanism:** “Show me how RVF stores and queries vectors. Cite the source,
- and separate working implementation from design documents.”
- - **Plan with evidence:** “Compare the RuvNet approaches for routing model calls. Explain
- the tradeoffs before recommending one.”
- - **Improve a codebase:** “Review this project's agent workflow. Identify a useful capability
- we already have, then propose the smallest change and how we would verify it.”
- - **Build with a bounded request:** “Use `/brain-build` to add a read-only report to this app,
- keep existing data intact, and verify the rendered result.”
- - **Resume work:** “Come up to speed on this project: what changed, what is still open,
- and which decisions have source or test evidence?”
- These are starting prompts, not promises of a particular result. Ask the assistant to cite
- what it read, say which tools executed, and name any missing prerequisite. Optional routing
- requires available, authorized executors; recommendations do not automatically install tools
- or authorize spending.
- ## How it works
- Brain separates **building the knowledge**, **retrieving evidence**, and **acting on it**.
- Public source is indexed into local RVF stores. At query time, the reader combines routing
- and retrieval lanes, reranks candidates and returns source evidence through MCP. The coding
- host uses that evidence while its own tools perform the work.
- 
- <details>
- <summary>ASCII Version (for AI/accessibility)</summary>
- ```text
- PUBLIC KNOWLEDGE YOUR LOCAL WORKFLOW
- RuvNet source + docs Your task in Claude Code / Codex
- | |
- v v
- Index source + symbols Skills + lifecycle guidance
- | |
- v v
- Signed public bundle ---------------> search_ruvnet (MCP)
- Local RVF stores + source passages Route -> retrieve -> rerank
- |
- v
- Source evidence: repo + path
- |
- v
- Host tools / authorized executors
- |
- v
- Changes + checks + receipts
- Eligible project memory (AgentDB)
- ```
- </details>
- The reader uses per-repository knowledge, capability cards, lexical and vector retrieval,
- and a shared cross-encoder ranking lane. It labels evidence and checks implementation
- requirements for queries that ask for code. A capability card helps find a product;
- it does not by itself prove an implementation exists.
- The public bundle contains RVF knowledge stores and source-passage sidecars. Project history
- is separate: eligible capture and recall use the project's canonical AgentDB store, including
- worktree resolution. Consent and failure reporting apply at those boundaries.
- **Source:** [retrieval implementation](kb/forge-ask-all.mjs),
- [MCP server](plugin/mcp/server.mjs), [Claude hooks](plugin/hooks/hooks.json),
- [Codex hooks](plugin/hooks/codex-hooks.json).
- ## What Brain brings to your workflow
- **Discover capabilities.** Ask about a need in plain language and get a starting point in the
- RuvNet ecosystem. Source-grounded advocacy aims to surface relevant capabilities early,
- with a reason they fit your task.
- **Read implementation.** Search results can include code bodies and source documents, with
- repository/path labels and evidence metadata. Evidence class matters: a design proposal and
- an implementation answer carry different weight.
- **Guide work across hosts.** The plugins share grounding and workflow skills while native
- hook adapters account for Claude Code and Codex differences. `/brain-prompt` helps refine a
- rough idea; `/brain-build` supplies a structured build contract. Configured routing can hand
- bounded work to supported native executors and record the choice. Routing registration is
- separate from observing a worker execute.
- **Retain useful project context.** Where an eligible project store and consent permit it,
- lifecycle capture records bounded, redacted observations and outcomes. Recall brings project
- facts and lessons back as evidence. Pending writes and incomplete restoration stay visible;
- inferred lessons do not silently become authoritative user instructions.
- **Inspect and maintain your environment.** RNBC shows installed components and supported
- settings. The coordinated updater uses one policy and shared owner lock for manual and
- scheduled runs, preserving existing managers and install paths.
- **Make proof part of the conversation.** Doctor, grounding receipts, update receipts and
- release gates distinguish a configured capability from an observed result. They help you
- identify the next check rather than infer success from a green registration line.
- ### Explore the ecosystem through Brain
- Ask about **Ruflo** for coordination, **RuVector / RVF** for vector knowledge,
- **AgentDB** for agent memory, **agentic-flow** for agent/model workflows,
- **Agentic QE** for quality engineering, or **SPARC** for a structured development method.
- Then deepen the answer with “show the implementation and prerequisites.” The bundle covers
- many more public repositories; its release census and source metadata define its coverage.
- ## From a question to reviewable work
- 
- <details>
- <summary>ASCII Version (for AI/accessibility)</summary>
- ```text
- ASK DISCOVER READ ACT VERIFY
- Your need -> Relevant -> Source -> Authorized -> Actual result
- capability + limits host tools + limitations
- ^ |
- | v
- Next task <---------------- Project evidence
- eligible memory
- ```
- </details>
- Start with the problem. Check the recommendation against its source. Make the change within
- the requested scope. Inspect the actual result, then retain useful evidence for the next task.
- The same sequence works for an explanation, a small repair or a larger delegated build.
- ## Stay current
- **4.6.0 introduces coordinated installed-tool updates.** Open RNBC and choose
- **Keep all tools updated**, with **Latest (recommended)** or **Alpha**. The default scope is
- the installed RuvNet suite; broader developer-tool maintenance is an explicit choice.
- Manual and scheduled runs share the coordinator, saved policy and owner lock.
- The schedule is **03:30 in your local time**.
- ```bash
- ruvnet-brain-update --check
- ruvnet-brain-update --apply
- ```
- Inspect the run receipt for what changed, failed or was excluded. A saved preference or a
- registered schedule establishes configuration; a completed run establishes its outcome.
- For an existing Brain installation, `ruvnet-brain --update` uses the update path.
- `ruvnet-brain --disable-nightly` disables its scheduled updates.
- **Code version and knowledge freshness are separate.** A code release can package the last
- published corpus without having refreshed every upstream repository. Public corpus production
- uses the protected release workflow; a consumer update downloads an available generation and
- does not rebuild upstream knowledge. Check `--doctor`, `SOURCE.json` and refresh receipts
- before treating an installation as current.
- The **4.6.0 published-corpus baseline** is **210 public stores · 176,584 public source chunks**.
- Those are bundle census values, not a claim that every upstream repository is fresh today.
- Later corpus publication may advance the knowledge generation independently of code changes.
- See [4.6.2 native update repair notes](docs/RELEASE-NOTES-4.6.2.md),
- [4.6.1 README/admin notes](docs/RELEASE-NOTES-4.6.1.md) and
- [4.6.0 coordinated-update notes](docs/RELEASE-NOTES-4.6.0.md) and the authoritative
- [update and release policy](CONTRIBUTING.md).
- ## Evidence and honest limits
- Brain supplies mechanisms and evidence; every claim has a boundary:
- - **Grounding guides the assistant.** Hooks and skills encourage source reads. Selected tool
- boundaries can refuse a call, but they do not guarantee the model always obeys, writes
- correct code or chooses the best design.
- - **Retrieval has a snapshot boundary.** Check dates and upstream source when currency matters.
- Coverage is limited to the indexed public material; the private-store fence excludes
- designated private stores from public bundles.
- - **Local search and model execution have different costs.** The reader runs locally;
- your host and optional provider calls may be metered. Brain does not claim automatic model
- switching or savings from merely registering a route.
- - **Memory has consent and delivery boundaries.** Queued capture is not committed history.
- Native delivery, exact readback and restoration require their own evidence.
- - **Publication is separate from source preparation.** The protected workflow binds a release
- to its artifact and public installation checks. A README edit, local test or passing subset
- does not establish a published release.
- <details>
- <summary>Recorded coverage baseline and how it is checked</summary>
- [-b58900?style=flat-square)](scripts/claims-verify.mjs)
- This retained badge is a recorded baseline, not a new measurement from this documentation
- revision. `npm run test:cov` creates the coverage artifact; `npm run claims:verify` checks the
- advertised number against the source-bound artifact. A new release must rederive its claims.
- Historical routing percentages and test totals are deliberately absent from this overview:
- their original runs do not establish the current candidate's behavior.
- </details>
- ## For contributors
- The repository uses Node.js ESM. Start with [CONTRIBUTING.md](CONTRIBUTING.md), which owns
- release, versioning, corpus and hook policies. Install checkout dependencies and run the
- relevant checks:
- ```bash
- npm ci
- npm test
- npm run single-source:check
- npm run wired:check
- ```
- Source and integration qualification are defined by `npm run release:qualify`; use the
- current procedure and unique report paths in CONTRIBUTING. Claims, packed-artifact checks,
- public installation and native-host evidence remain separate gates.
- Useful places to read:
- - [`plugin/`](plugin/) — native plugins, skills, lifecycle hooks and MCP shell.
- - [`kb/`](kb/) — retrieval implementation and knowledge tooling.
- - [`scripts/`](scripts/) — install, update, console and release checks.
- - [`docs/adr/`](docs/adr/) — architecture decisions and their acceptance limits.
- - [`SECURITY.md`](SECURITY.md) — security boundaries and reporting.
- - [`explainer/`](explainer/) — source for the public visual walkthrough. The companion page
- is introductory; current implementation and policy are documented in this repository.
- ## Community and license
- Have a concrete example that helped, or a source-grounded failure we can reproduce?
- Open an [issue](https://github.com/stuinfla/ruvnet-brain/issues) or join
- [Discussions](https://github.com/stuinfla/ruvnet-brain/discussions).
- RuvNet Brain is **MIT licensed**. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.