github.com/ChicagoHAI/NeuriCo @main

NeuriCo (Neural Co-Scientist, inspired by Enrico Fermi) takes structured research ideas and coordinates agents to find resources, design and run experiments, analyze results, and document the work.

Key features

Requirements

Minimal (choose one):

• Docker: Git and a running Docker installation
• Local uv: Git, Python 3.10+, and uv

Provider access:

• Claude Code, Codex, or Gemini CLI
• Provider login uses OAuth; provider API keys are not required

Recommended for GitHub publishing:

• A classic GitHub token with repo scope; create one and follow Configuration
• Skip this when research should remain local

Quick start

Choose Docker or local uv and use the same route throughout.

1. Install

Docker

git clone https://github.com/ChicagoHAI/neurico.git
cd neurico
./neurico setup --quick

For Codex or Gemini, run ./neurico setup instead.

Install the Docker route with one command

curl -fsSL https://raw.githubusercontent.com/ChicagoHAI/neurico/main/install.sh | bash

The installer clones NeuriCo into ./neurico and opens the full setup wizard.

Local uv (native)

git clone https://github.com/ChicagoHAI/neurico.git
cd neurico
uv sync
cp .env.example .env
claude  # or: codex, gemini

More information about provider authentication, workspace location, and optional services is available under Configuration.

2. Write and submit an idea

Create a YAML idea file:

idea:
  title: "Do LLMs distinguish causation from correlation?"
  domain: artificial_intelligence
  hypothesis: >
    Explicit causal prompts improve causal-reasoning accuracy compared with
    otherwise equivalent direct prompts.

Submit it and keep the printed <idea_id>:

Additional input formats and submission options are available under Idea submission.

3. Choose a research mode

Replace <idea_id> with the ID printed during submission.

Detailed workflows and options are available under Research modes.

That's it—NeuriCo turns your hypothesis into experiments, evidence, and a reproducible research project.

Configuration

CLI authentication

Claude Code, Codex, and Gemini CLI use OAuth login, not API keys. Log in once on the host:

claude  # or: codex, gemini

In Docker mode, credentials are automatically mounted into containers.

Workspace configuration

Workspaces default to workspaces/. With Docker, change the location through the configuration menu:

./neurico config

With local uv, copy the workspace example and set parent_dir:

cp config/workspace.yaml.example config/workspace.yaml

workspace:
  parent_dir: "/path/to/your/workspaces"
  auto_create: true

Environment variables (.env)

With Docker, configure environment variables through the interactive menu:

./neurico config

With local uv, edit .env directly. Here's what each variable does:

GitHub publishing — GITHUB_TOKEN is required only when publishing to GitHub; GITHUB_ORG is optional (uses the personal account if empty)

Paper Finder and agent API keys

Paper Finder — S2_API_KEY and either OPENROUTER_KEY or OPENAI_API_KEY required for full paper-finder; COHERE_API_KEY optional (improves ranking)

Agent API Keys — optional, provided to the agent during automated experiments

Idea submission

NeuriCo accepts YAML, Markdown or text, and IdeaHub pages. Follow the Idea quickstart to prepare your first idea. See the complete Idea guide for all available fields and options.

Without --submit, Markdown, text, and IdeaHub inputs are converted to a YAML draft for review; submit the reviewed draft later with the YAML command above. Add --submit to submit the converted YAML directly to NeuriCo.

Publishing options

If GITHUB_TOKEN is configured, submission also creates and prepares a research repository.

Research modes

Standard

Standard performs one end-to-end research run: it finds resources, designs and executes experiments, analyzes the results, and writes a paper draft. Choose it when you want one complete pass without iterative improvement.

Common options

Remote compute backends

Advanced Standard pipeline controls

AutoResearch

AutoResearch starts from a scored baseline and improves it iteratively. Each iteration proposes one change, runs the experiment, and scores the result. The change is kept only when it improves the current best score.

Start fresh

Create a scored baseline and run one improvement iteration by default.

Continue an existing AutoResearch workspace

Resume an earlier AutoResearch run without repeating resource discovery or baseline creation.

Bootstrap a Standard workspace

Use this when a Standard run already has useful results but no AutoResearch baseline. NeuriCo scores the existing workspace and prepares it for continuation; it does not run an improvement iteration.

Continue from the new baseline with --continue-autoresearch.

Common options

The Standard provider, compute, permission, paper, and GitHub options also apply to AutoResearch.

Advanced AutoResearch and bootstrap controls

For continuation requirements and details about scoring, checkpoints, and recovery, see the AutoResearch guide.

HITL AutoResearch

Human-in-the-loop (HITL) AutoResearch adds a manager that coordinates the research agents and asks for your input at key decisions. You can review plans and proposals, give feedback, and guide which research directions continue. The web and terminal interfaces connect to the same manager conversation and workspace.

Web interface

The web interface opens at `http: