IRP

English · 简体中文 · 日本語 · 한국어 · Español · Italiano

IRP: Build any paper. Prove every claim.

One MCP server and CLI that lets your coding agent turn a research paper into working code, run it, and prove claim by claim how close it gets.

Give it a paper. Get back working code and a report you can check without trusting the agent.

Quick start · How IRP works · The report · What you can reproduce · FAQ · Documentation

uvx irp-agents setup

[!IMPORTANT]

Get IRP from Noshadi-sec/irp or the

irp-agents package on PyPI. Follow the

installation and release links from these official sources. A similar

repository name or copied README does not establish that a download is official.

---

Found a paper with no code, or code you cannot trust? Ask your agent to build it with IRP. The agent reads the paper, records every number it claims, writes the implementation, runs it and compares the results. IRP does the fetching, running and record keeping, and refuses the shortcuts: a number typed by hand never counts, a shortened run never counts, and the report is written only from the evidence log.

IRP connects your agent (Claude Code, Codex or Cursor) to tools for paper intake, environments, runs, measurements and verdicts. You can use the same tools from your terminal. Everything runs locally; IRP never calls a model, and data goes only where you send it.

Quick start

Set up your agent

With uv installed, run:

uvx irp-agents setup

Choose your agents, review the proposed changes, and approve them. Setup adds IRP's MCP server and its workflow skill, with backups of existing configuration. Restart your agent afterward.

Setup supports Claude Code, Codex and Cursor. Other MCP clients can use manual registration.

Ask your agent

Build arXiv 2501.12345 and check Table 2.

You get back a working code folder plus a report: every claim, the paper's number, your number, and a verdict.

Use the terminal

Every tool is also a command. Fetch a paper into a new study and read its outline:

irp fetch 2501.12345 --study ~/studies/example

irp section index --study ~/studies/example

To install the irp command for regular use:

uv tool install irp-agents

irp --help

See the CLI guide for the full workflow from the terminal.

Check readiness

irp doctor

Doctor checks Python, uv, git, Docker, GPUs, disk space and your agents' registrations, and changes nothing.

Update IRP

IRP changes quickly. For an installed command:

irp update

With uvx, refresh your agent setup with uvx irp-agents@latest setup, review the plan, and restart your agent.

How IRP works

Your agent thinks; IRP acts and keeps the receipts. The agent reads the paper, writes code and decides what to run. Every action goes through one core, so the CLI and the MCP server behave the same, and every step lands in an append-only, hash-chained evidence log. The report is built from that log alone.

The workflow skill gives the agent six hard rules, and the tools enforce them wherever they can:

1. Never type, estimate or copy a number as a result.
2. Never change the paper's method to make a run succeed; record a guess instead.
3. Report "could not run" with the blocking error instead of pushing through.
4. Run the smallest faithful version first; shortened runs never count.
5. Record every claim before writing any code.
6. Ask before any paid compute.

The report

The report is the product: a person must be able to check every verdict without trusting the agent. It has five parts: the claim table, four verdicts (reproduced, close, not reproduced, could not run), the guess list, the method map from equations to code lines, and provenance (arXiv ID and version, file hashes, git commit, lock files, GPU, seeds, every command with its exit code, and a verify command that rechecks the hash chain).

The agent cannot finish until every claim has a verdict with evidence.

Example report.md (made-up numbers):

# Reproduction report: Example Paper (arXiv 2501.12345v2)

Result: 2 reproduced, 1 close, 1 could not run (of 4 claims)

Guesses

• g1 Warmup length not stated: used 5 epochs. Why: as in cited paper [12].

Method map

• Eq. 3 (loss) -> code/src/loss.py:41
• Algorithm 1, line 4 -> code/src/train.py:88

Provenance

• Paper: arXiv 2501.12345v2, source and PDF hashes
• Code: git commit 3f2a9c1 (clean)
• Commands logged: 37, 37 with an exit code
• Evidence log: 112 records, head sha256:…, verified
• Verify: irp verify --study ~/studies/example

See evidence and report for every field.

What you can reproduce

IRP requires Python 3.11+ on macOS or Linux. Additional tools depend on the paper:

IRP supports computational papers: machine learning, algorithms and simulations. It does not support wet-lab work or anything weapons-related.

Benchmark

Five light papers — official code exists, each runs on a CPU in minutes — rebuilt from the paper alone and checked claim by claim. Every number comes from a verified evidence log; re-check any study with irp verify --study benchmarks/studies/ .

Across 8 claims: 6 reproduced, 1 close, 1 not reproduced (87.5% reproduced or close), ~160s and $0 of paid compute per paper. Selection criteria and the full set are in benchmarks/golden/papers.json; the protocol and summarize.py are in benchmarks/.

If you build a paper with IRP, share the report in an issue with the paper, your question, and what you found.

FAQ

Which agents can use IRP?

Any agent that supports local MCP servers. Setup configures Claude Code, Codex and Cursor; other clients can use manual registration.

Does IRP call an AI model or upload my paper?

No. Your agent is the brain; IRP never calls a model and has no API key. It downloads papers from arXiv, installs packages through uv or Docker, and runs code on your machine. Your agent receives the tool results, and its model provider has its own data policy.

Is running a paper's code safe?

Running code is running code. A uv virtual environment is not a sandbox: the code runs with your permissions. Use create_env with backend: "docker" for code you did not write or do not trust, and runs mount only the study's code directory. See security.

What does "not reproduced" mean?

That this run, with the recorded guesses, did not reach the paper's number within the stated bar. The report says "not reproduced by this run" and lists every guess. It is evidence about one attempt, not a verdict on the paper; contact the authors before publishing it.

The paper has official code. Should I use IRP?

IRP builds missing code from the paper. To check that existing code reproduces its README's numbers, a tool such as paper-repro fits better. IRP is still useful for testing a paper by hiding its code and comparing your rebuild with it afterwards.

Can IRP spend money?

Only on paid GPU providers, only after you record a price and a budget at a terminal with irp budget, and only after you approve the estimate the agent shows you. The run's time limit equals the estimated hour