ruvn

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.

What it does (in plain language)

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.

How sources are graded

| 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.

Install & use

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.

Claude Code (one command)

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 init

Then, 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.

Other hosts

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 |

Try it against a real model (OpenRouter)

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 question

Each 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)

How it's built

• 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:research template), then extended to all 9 hosts.

Part of ruv-neural

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.

License

MIT