A research agent that turns a question into a graded, cited evidence dossier — built for gamma-entrainment (40 Hz) protocol research.
ruvn is a small AI-agent "harness": a set of specialist agents plus the config to drop them into your AI coding host (Claude Code, Codex, Copilot, and more). You ask a research question; it runs a disciplined pipeline that searches, grades every source, synthesizes only from the good ones, adversarially fact-checks the result, and hands back a dossier where every claim is cited.
It was built for the ruv-neural project — comparing 40 Hz stimulation modalities, dosing, responder profiles, and safety evidence — but it works for any research question.
Scope: a research tool. It grades and cites evidence; it does not give medical advice or make efficacy claims. Treat its output as a starting dossier to verify, not a conclusion.
Most "ask an AI" research blends good and bad sources into one confident answer. ruvn refuses to. It runs six agents in a line, and each agent only sees the previous agent's output — so information has to pass through grading and verification gates before it reaches you:
scout → web-searcher → source-grader → synthesizer → fact-checker → citer
| # | Agent | What it does | Plain English |
|---|---|---|---|
| 1 | scout | Breaks your question into 3–7 precise sub-questions | "What exactly do we need to find out?" |
| 2 | web-searcher | Runs each sub-question, collects raw hits | "Go find the sources." |
| 3 | source-grader | Grades every source A/B/C/D by authority, freshness, relevance | "Which of these can we trust?" |
| 4 | synthesizer | Writes findings using grade A/B sources only | "Summarize — but only from the good stuff." |
| 5 | fact-checker | Adversarially re-checks every claim | "Try to prove each statement wrong." |
| 6 | citer | Final pass: every claim must cite a graded source | "No claim ships without a receipt." |
You get back: a dossier in Markdown — a TL;DR, a body where every claim is cited, and a bibliography with a letter grade next to each source.
| Grade | Means |
|---|---|
| A | Primary source (paper, official doc), under ~2 years old, on-topic |
| B | Reputable secondary source (major outlet, expert), under ~5 years |
| C | Tertiary (Wikipedia, summary) — context only, not evidence |
| D | Discarded (forum post, unsourced claim, dead link) |
The synthesizer is only allowed to use A and B. That's the whole point.
ruvn runs inside your AI host — it adds the research pipeline to a host you already use. The package ships adapters for 9 hosts; pick yours.
npm i -g @ruvnet/ruvn # installs the `ruvn` command
ruvn init # wires the harness into Claude Code (.claude/ settings + plugin)
ruvn doctor # health check — confirms the kernel + host adapter load
# or one-off, no install: npx @ruvnet/ruvn initThen, in Claude Code, ask it to run the research pipeline on your question — the agents and the rubric in CLAUDE.md are now available to it.
The package already contains the config each host needs — copy/point your host at it (see install.md for per-host steps):
| Host | What ships |
|---|---|
| Claude Code | .claude/settings.json, .claude-plugin/plugin.json |
| Codex | .codex/config.toml, AGENTS.md |
| GitHub Copilot | .vscode/mcp.json, .github/copilot-instructions.md |
| OpenCode | .opencode/opencode.json |
| GitHub Actions | .github/workflows/ruvn.yml, .github/actions/ruvn/ |
| pi-dev | AGENTS.md, SYSTEM.md, trust.json |
| Hermes | cli-config.yaml, optional-mcps/ruvn.json |
| OpenClaw | .openclaw/openclaw.json |
| RVM | rvm.manifest.toml, capability-table.json |
You can validate the whole agent set end-to-end against a live model. Set an OpenRouter key and run:
export OPENROUTER_API_KEY=sk-or-... # your OpenRouter key
npm run validate:openrouter # runs all 6 agents on a sample questionEach agent is exercised against its model tier (sonnet/haiku) and must return a sensible, on-task response. The same check runs under npm test automatically when OPENROUTER_API_KEY is set (it's skipped otherwise), so unit tests stay offline-friendly.
npm install
npm run build # TypeScript → dist
npm test # unit tests (+ OpenRouter integration if a key is present)- Kernel:
@metaharness/kernel— orchestration, memory, trajectory (no model calls; your host provides the model). - Agents: plain prompt + model-tier definitions in
src/agents/— easy to read and tweak. - Hosts:
@metaharness/host-*adapters — one package per supported host. - Generated with
metaharness(vertical:researchtemplate), then extended to all 9 hosts.
ruvn is the research front-end for ruv-neural — the open closed-loop OS for gamma-entrainment research. Use ruvn to gather and grade the evidence; use ruv-neural to run, measure, and sign the protocols.
MIT