README.md

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.

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

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)

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

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.

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://localhost:7890. Opening it does not start research. Click Start AutoResearch in the upper-right corner, review the run settings, and start the run.

Terminal interface

Opening the terminal interface does not start research. Enter /run and answer the prompts. NeuriCo detects whether to start a fresh HITL run or continue the existing workspace.

For the manager and human review workflow, scoring decisions, and recovery, see the HITL AutoResearch guide.

Docker utilities

./neurico update   # Pull the latest code and Docker image
./neurico shell    # Open a shell in the container
./neurico help     # Show all commands

Research outputs

A research workspace can contain:

workspaces/<research-workspace>/
├── README.md         # Project overview
├── REPORT.md         # Research findings
├── STATE.md          # Pipeline state
├── src/              # Experiment code
├── results/          # Metrics and generated results
├── logs/             # Run logs and transcripts
├── artifacts/        # Models and checkpoints
├── scoring/          # When scoring is enabled
├── notebooks/        # With --use-scribe
└── paper_draft/      # When paper writing is enabled

Submitted idea files move through ideas/submitted/, ideas/in_progress/, and ideas/completed/ as runs progress. Workspace contents depend on the mode and run options.

flowchart LR
    A["Idea (YAML, text, or IdeaHub)"] --> B["Submit and validate"]
    B --> C{"Choose a mode"}
    C --> D["Standard"]
    C --> E["AutoResearch"]
    C --> F["HITL AutoResearch"]
    D --> G["Research workspace"]
    E --> G
    F --> G
    G --> H["Code, results, logs, and reports"]
    G --> I["Optional scoring and paper"]
    G --> J["Optional GitHub publication"]

Customizing NeuriCo

Selected domains

See the complete domain definitions for all supported domains and domain keys.

Templates and skills

Files under templates/ control NeuriCo's agent behavior. Docker reads these files directly from the checkout, so changes take effect without rebuilding the image.

Documentation

ClawHub provides installation and onboarding metadata. Run NeuriCo with Docker or local uv. The documentation index separates user guides from developer, internal, and legacy documents.

Contributing

Contributions are welcome. Areas of interest include domain templates, evaluation contracts, experiment integrations, and research-mode improvements. Open an issue before starting a large change.

Citation

If you use NeuriCo in research, please cite:

@software{neurico_2025,
  title={NeuriCo: Autonomous Research Framework},
  author={Haokun Liu, Chenhao Tan},
  year={2025},
  url={https://github.com/ChicagoHAI/neurico}
}

Acknowledgments

Some skills in templates/skills/ were inspired by claude-scientific-skills (MIT License, K-Dense Inc.). See NOTICE for details.

License

Apache 2.0. See LICENSE.

For questions and feedback, open an issue or join the NeuriCo Discord.