Content
align=" <img src="docs/assets/rh-github-header.png" alt="research harness" width="760"/>
</p>
<p align="center">
<a href="README.md"><b>Simplified Chinese</b></a> · <a href="README.en.md">English</a>
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"/></a>
<img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python"/>
<img src="https://img.shields.io/badge/MCP-compatible-orange.svg" alt="MCP"/>
</p>
<p align="center"><strong style="font-size:1.75rem;">Making Evidence Reliable, Process Traceable, and Autonomous Long-Term Automated AI Research</strong></p>
Research Harness is the harness layer for research agents, providing evidence status, process recording, tool interfaces, and feedback loops. This enables retrieval, reading, judgment, and writing to become long-term, sustainable, and automated research processes.
Applicable to Codex, Claude Code, Gemini CLI, OpenCode, Cline, Cursor Agent, Kilo Code, and other mainstream AI programming agents. It also supports access to third-party agent tools like OpenClaw through agent profiles.
The current subsystem status and public tool interface are available at [docs/STATUS.md](docs/STATUS.md).
## Get Started in 3 Minutes
If you just want to confirm if RH can run on your machine, follow these steps:
```bash
git clone https://github.com/Biajin-PKU/research-harness.git
cd research-harness
./setup.sh
rh --json doctor
rh skill install --agent codex
rh skill verify --agent codex
rh skill list --group-by-suite
```
Then, pass this to Codex, Claude Code, or other agents with installed RH skills:
```text
Please read docs/agent-guide.md and docs/PAPER_MANAGEMENT.md.
research topic around "robust budget pacing for online advertising".
Retrieve recent papers, filter useful ones into the database, and generate the first version of the literature map.
All papers bound to the topic and key as RH artifacts.
```
No API key is required to complete check, skills installation, public, and local demo story Configure LLM routes when deep read, claim extraction, annotation, and capabilities are needed.
## Why RH?
Ordinary agents can papers, summarize PDFs, extract viewpoints, and generate drafts. However real challenge in research is making these actions accumulate sustainably. After a conversation ends, papers, claims, gaps, baselines, experimental judgments, and draft versions often scatter in chat records, temporary files, and human memory. Research Harness solves this problem by making the research process evidence-based, traceable, and optimizable.
## Product Features
| Feature | Description |
|---|---|
| **Evidence Reliability** | Bind papers, evidence fragments, and source chains to reduce unfounded inferences. |
| **Process Traceability** | Record judgments, stages, versions, and gating results to support replay, review, and continuation. |
| **Autonomous Optimization** | Precipitate failures, corrections, contradictions, and feedback to allow subsequent rounds to improve based on evidence. |
| **Long-Term Tasks** | Support continuous, automated research across sessions, tools, and agents. |
Public Entries
RH's are organized by task suites. `skills/manifest exposes `public_suite`, `task_type`, `_level`, inputs, outputs, and estimated time for. This allows agents or to fold complex tool interfaces into a few understandable entries.
| Suitable for | Representative Skills |
|---|---|---|
| **research** | Create topics, search papers, make literature maps, extract claims, find gaps | `research-init`, `-search`, `literature-mapping`, `claim-extraction`, `` |
| ** | Draft chapters, edit assemble submissions/review packages |-writing`, `section-d`, `figure-qualitypublication-pack` |
|** | Verify paper identities, perform evidence gating, audit provenance |-verify`, `evidence`, `provenance-review| **zotero** | Sync Zotero, read local PDFs, plugin adaptation | `paper-sync`, `paper-reading-annotation`, `rh-zotero-plugin-adapter` |
| **benchmark** | Evaluate final bundles, review operational contracts, support self-optimization | `final-bundle-quality`, `task-taxonomy` |
## Core Capabilities
| Capability | Description |
|---|---|
| Paper Pool Management** | Retrieve, filter, and store papers around research topics, maintaining a sustainable, expandable literature pool. |
| 🧾 **Research Statement Extraction** | Extract research statements, hypotheses, datasets, metrics, and from papers. |
| 🧭 **Source** | Record relationships between papers, statements, evidence, outputs, and stage decisions for traceable conclusions. |
| 🧪 **Gap and** | Identify research gaps, key baselines,, and experiment directions. |
| 📝 **Evidence-Constrained Writing** experiment briefs, proposals, related work, or draft corresponding evidence chains. |
| 🚦 **Stage Scheduling and Gating** | Manage long-term research processes through, gating checks, consistency checks, and output recording. 🔁 **Autonomous Optimization Loop** | Record, review feedback, contradiction discoveries, and corrections to support continuous improvement. |
| **Zotero Reading Workflow** | Integrate local into RH research states using Zotero libraries, PDFs, and reading scenes. |
🔌 **Multi-Agent Access** | Support mainstream AI programming agents and access third-party agent tools through agent profiles. |
## Installation Tips
First, install a commonly used AI programming agent. Here's an example with Codex:
```bash
npm install -g @openai/codex
```
Then, pass this to Codex:
```text
Please install Research Harness for the current environment:
1. Clone the repository: https://github.com/Biajin-PKU/research-harness.git
2. Enter the project directory and run ./setup.sh
3. Run rh --json doctor to verify the installation
4. Install RH skills for Codex: rh skill install --agent codex
5. Run rh skill verify --agent codex to skills are available
6 any steps fail, diagnose and fix the issues before proceeding
```
For manual installation,, and MCP configurations,- [English Quickstart/quickstart.md)
- [Demo story](docs/.md)
- [Showcase bundle](docs/showcase-bundle## Scenario Demonstration
The can be directly given to RH organizes these instructions into structured states like topics, paper pools, claims, gaps, artifacts, and provenance.
**Creating a Research Topic from Scratch**
**Prompt**
```text
Create a research topic around "robust budget pacing for online advertising".
Retrieve recent papers, filter useful ones into the database, and establish the first version of the literature map.
```
**RH Execution**: Create a topic, retrieve and store papers, maintain a paper pool, and record the literature map as a sustainable research output.
**Turning Reading into Evidence Assets**
**Prompt**
```text
Read the most relevant papers in this topic.
Extract research statements, key hypotheses, limitations, datasets, metrics, and reproducibility risks.
```
**RH Execution**: Call paper reading and statement extraction capabilities, write claims, hypotheses, limitations, and risks into the topic state, and preserve source relationships.
**Converging from Evidence to Experimental Directions**
**Prompt**
```text
Identify research gaps based on recorded evidence.
Compare relevant baselines and generate experiment briefs for the most promising directions.
```
**RH Execution**: Identify gaps and baselines from stored papers and statements, and converge experimental directions into evidence-constrained experiment briefs.
**Generating Reviewable Drafts**
**Prompt**
```text
Draft related work based on the current topic's paper pool and claims.
Each key conclusion must retain sources.
```
**RH Execution**: Organize writing materials from the paper pool, claims, and provenance to generate reviewable, traceable chapter drafts.
## Usage Entries
| Entry | Suitable | Documentation |
|---|---|---|
| **Zotero Sidebar Research workflows centered on papers/literature libraries | [docsero-rh-panel.md](docs/zotero-rh| **Mgent Client** | Workflows for Codex, Claude Code, Gemini CLI, OpenCode, Cline, Cursor Agent, Kilo Code, and other agents | [docs/agent-guide.md](docs/agent-guide.md) |
** | Local terminals, scripts, batch processing, automation | [docs/quickstart.md/quickstart.md) |
| **Python API** |, pipelines, programmatic [docs/python-api.md](docs/python-api.md) Open-Source Maintenance and Codex
Research Harness itself uses Codex to maintain its open-source workflow: generating and reviewing replaying regression cases, checking release hygiene, updating documentation, reviewing MCP/CLI/Zotero bridge changes, and assisting in security checks before merging. RH's goal is not just to let agents generate one-time answers but to record judgments, failures, corrections, and evidence throughout the maintenance process, accumulating into reusable project states.
For open-source maintainers, RH provides a transferable agent work mode: Codex handles execution and verification, while RH manages papers, claims, artifacts, gates, provenance, and long-term task states. This allows complex research projects to remain traceable, recoverable, and reviewable across multiple rounds, tools, and sessions.
## Documentation Navigation
- [Documentation Home](docs/index.md)
-start](docs/quick)
- [Agent Userdocs/agent-guide.md)
- [Paper Management Specifications](-management.md)
- [MCP Tools and Workflows](docs-tools.md)
Zotero Integration/zotero-integration.md)
- Overview](docs.md)
- [](docs/TROUBLE.md)
--Tool Support Matrix](docs/tool-support.md)
- [Security Policy](SECURITY.md)
## License
[MIT
