Researcher AI

Researcher AI turns Sakana AI's AI Scientist-v2 into an auditable MCP product for ChatGPT, Codex, and Claude Code.

It is more than a prompt wrapper: the repository contains rich research briefs, deterministic ranked planning, a shared MCP server, a ChatGPT Apps SDK widget, persistent tenant-isolated projects and jobs, retry deduplication, graceful cancellation, audit logs, a mandatory manuscript-disclosure pass, Codex and Claude Code plugins, local marketplace catalogs, and deployment assets for isolated execution.

Safety default: installations start in deterministic mock mode. Live experiments execute LLM-written code and must run inside a dedicated sandbox. The public no-auth deployment must set PUBLIC_REVIEW_MODE=stateless; that profile exposes only status and one deterministic mock workflow, then deletes its isolated working state before returning. Never expose the persistent tool set with AUTH_MODE=none to the public internet.

What is included

Surface	Package	Purpose
ChatGPT app	HTTP MCP at /mcp + single-file widget	Remote project, job, and artifact workflow
Codex plugin	plugins/researcher-ai/.codex-plugin/plugin.json	Shared skill and bundled stdio MCP server; can link to a ChatGPT app ID
Claude Code plugin	plugins/researcher-ai/.claude-plugin/plugin.json + .mcp.json	Shared skill, research-manager agent, and bundled stdio MCP server
AI Scientist integration	Pinned Git submodule + native/Docker runners	Ideation and experiment execution at commit 96bd51617cfdbb494a9fc283af00fe090edfae48

The local/private MCP server exposes eleven tools: service status, rich project creation/listing/dashboard, ideation start/list, experiment start, job status/cancellation, and artifact list/read. The public ChatGPT review deployment exposes two non-persistent tools: service status and a complete deterministic mock workflow that returns ranked directions plus four downloadable inline audit artifacts.

Architecture

flowchart LR
  C["ChatGPT / Codex / Claude Code"] -->|"MCP over HTTP or stdio"| M["Researcher AI MCP service"]
  M --> A["Authentication and tenant boundary"]
  A --> S["Persistent project and job store"]
  A --> Q["Bounded job queue"]
  Q --> R{"Runner mode"}
  R -->|"default"| X["Deterministic mock"]
  R -->|"dedicated service container"| N["Native sandbox copy"]
  R -->|"recommended live mode"| D["Per-job Docker container"]
  D --> U["Pinned AI Scientist-v2"]
  N --> U
  U --> P["Disclosure pass and auditable artifacts"]
  P --> S

Quick start

Requirements: Node.js 22+, npm 10+, Git, and Python 3 for the disclosure helper. Live AI Scientist execution additionally requires Linux, NVIDIA/CUDA/PyTorch, the upstream Python dependencies, and appropriate model-provider credentials.

git clone --recurse-submodules https://github.com/samsamurai301/Researcher-AI.git
cd Researcher-AI
npm ci
npm run validate
npm run smoke

Start the local HTTP service in safe mock mode:

cp .env.example .env
npm start

Health endpoints are http://localhost:8000/health and /ready; MCP is http://localhost:8000/mcp.

Install the plugins locally

Release checkouts already contain the bundled MCP server and license files. After changing the service locally, regenerate that bundle with:

npm run build

Codex:

codex plugin marketplace add /absolute/path/to/Researcher-AI
codex plugin add researcher-ai@personal

Claude Code:

claude plugin marketplace add /absolute/path/to/Researcher-AI --scope project
claude plugin install researcher-ai@researcher-ai --scope project

Both local plugins use stdio MCP and default to mock execution. Set RESEARCHER_RUNNER, AI_SCIENTIST_ROOT, and provider credentials in the host environment only after reviewing SECURITY.md.

Live runner modes

• mock: deterministic integration verification; no model calls and no scientific claims.
• native: copies the pinned source into a job-local directory and starts Python directly. Use only when the entire service already runs in a dedicated, disposable execution container.
• docker: starts a resource-limited container per job. This is the intended live mode on a rootless-Docker GPU host.

Build the AI Scientist runner image:

docker build --platform linux/amd64 -f infra/Dockerfile.ai-scientist -t researcher-ai-scientist:0.2.0 .

See Deployment for HTTP/OIDC and GPU-host setup, and Publishing for ChatGPT, Codex, and Claude marketplace release steps.

Development

npm run typecheck
npm test
npm run build
npm run smoke
npm run validate

Generated state is stored in .researcher-ai/ by default and is ignored by Git. The service marks interrupted jobs as failed on restart so stale executions are never reported as still running.

License and scientific integrity

The original Researcher AI wrapper is Apache-2.0 licensed. AI Scientist-v2 is a pinned third-party component under The AI Scientist Source Code License, which includes use restrictions and a mandatory prominent disclosure for generated scientific manuscripts, papers, and technical reports. Read THIRD_PARTY_NOTICES.md and the complete upstream license before use or distribution.

Researcher AI inserts the required disclosure into generated TeX/PDF artifacts, but automation is not a substitute for legal review, citation verification, independent scientific review, or responsible publication decisions.