ruvn is an AI research agent harness designed to transform research questions into graded, cited evidence dossiers. Built specifically for gamma-entrainment and 40 Hz protocol research through the ruv-neural project, it functions as a disciplined pipeline that refuses to blend credible and unreliable sources into a single confident answer. The tool works for any research question but maintains strict evidentiary standards throughout its process.
The core mechanism operates through six sequential agents, each processing only the output of its predecessor. This gating structure ensures information passes through grading and verification checkpoints before reaching the user. The scout agent breaks down the initial question into three to seven precise sub-questions, establishing exactly what needs investigation. The web-searcher then runs each sub-question and collects raw source hits. The source-grader evaluates every source using a four-tier system: Grade A for primary sources under two years old, Grade B for reputable secondary sources under five years old, Grade C for tertiary sources like Wikipedia used only for context, and Grade D for discarded sources including forum posts and unsourced claims. The synthesizer writes findings using only Grade A and B sources, enforcing the tool's central constraint. The fact-checker then adversarially re-examines every claim to identify weaknesses. Finally, the citer ensures no claim reaches the user without citation to a graded source.
The output is a Markdown dossier containing a TL;DR summary, a body where every claim includes citations, and a bibliography with letter grades assigned to each source. This structure transforms research from a confidence-blending exercise into an evidence-accountability system.
ruvn ships as a JavaScript package with adapters for nine distinct AI hosts: Claude Code, Codex, GitHub Copilot, OpenCode, GitHub Actions, pi-dev, Hermes, OpenClaw, and RVM. Each host receives its own configuration files and integration points, allowing users to drop the research pipeline into their existing AI coding environment. Installation varies by host but follows documented per-host steps. The package includes host-specific configurations such as Claude's settings and plugin JSON files, Codex's config.toml, Copilot's MCP and instructions files, and workflow definitions for GitHub Actions.
The tool can be validated end-to-end against live models through OpenRouter, with agents exercised against their designated model tiers. The same validation runs automatically during npm test when an OpenRouter API key is present, keeping unit tests offline-friendly otherwise. The kernel uses the metaharness orchestration library for memory and trajectory management without making model calls directly, delegating that responsibility to the host. Agents are defined as plain prompts with model-tier specifications in the src/agents directory, making them readable and easily customizable.
ruvn was generated from the metaharness agent-harness-generator using the vertical:research template, then extended to support all nine hosts. It functions as the research front-end for the ruv-neural project, an open closed-loop operating system for gamma-entrainment research. Users gather and grade evidence with ruvn, then use ruv-neural to run, measure, and sign the actual protocols. The tool explicitly positions itself as a research instrument that grades and cites evidence rather than providing medical advice or making efficacy claims, treating its output as a starting dossier for verification rather than a final conclusion. The project is released under the MIT license.
