ruvn

KO | EN

gitlite — search

#python #hacktoberfest #ai #llm #rust #deep-learning #nodejs #awesome #kubernetes #awesome-list #security #openai #mcp #open-source

(★ 11)

ruvn — AI research harness that turns a question into a graded, cited evidence dossier (gamma-entrainment / 40 Hz protocol research). 9 hosts, OpenRouter-validated.

ruvn Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](https://github.com/ruvnet/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)

```bash
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:

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

```bash
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`](https://github.com/ruvnet/agent-harness-generator) (`vertical:research` template), then extended to all 9 hosts.

## Part of ruv-neural

`ruvn` is the research front-end for [ruv-neural](https://github.com/ruvnet/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

ruvn

ruvn Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ruvn

ruvn Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README