Native

NeuriCo (Neural Co-Scientist, inspired by Enrico Fermi) is an autonomous research framework that takes structured research ideas and orchestrates AI agents to design, execute, analyze, and document experiments across diverse domains.

Requirements

Minimal (one of):

• Option 1: git + Docker (recommended)
• Option 2: git + Python 3.10+ + uv

Resource — access to at least one AI coding CLI (uses OAuth login, not API keys):

• Claude Code (recommended), Codex, or Gemini CLI

Recommended:

• GitHub token (classic, repo scope) — for auto-creating repos and pushing results. Create here

Optional API keys (enhance functionality):

Setup tiers:

• Basic: CLI login + GITHUB_TOKEN — full NeuriCo functionality
• Enhanced: + OPENAI_API_KEY — LLM repo naming + IdeaHub support
• Full: + S2_API_KEY (+ optional COHERE_API_KEY) — paper-finder literature search

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

cd NeuriCo
./neurico fetch <ideahub_url> --submit --run --provider claude --write-paper --full-permissions

git clone https://github.com/ChicagoHAI/neurico
cd neurico
./neurico setup      # Interactive wizard: pulls Docker image, configures API keys

Setup

Docker (Recommended)

Docker provides an isolated environment with GPU support, CLI tools, LaTeX, and paper-finder pre-installed. The pre-built image includes everything — Python venvs, CLI tools (Claude/Codex/Gemini), LaTeX, and paper-finder — so you skip the long build step.

# Clone the repo (provides CLI scripts, config, templates, and idea examples)
git clone https://github.com/ChicagoHAI/neurico
cd neurico

# Option A: Pull pre-built image (faster, ~2 min download)
docker pull ghcr.io/chicagohai/neurico:latest
docker tag ghcr.io/chicagohai/neurico:latest chicagohai/neurico:latest

# Option B: Build from source (~10-15 min)
./neurico build

# Configure
./neurico config   # Interactive menu for API keys and settings

# Login to your AI CLI (one-time, on your host machine)
claude   # or: codex, gemini
# Credentials are automatically mounted into containers

Note: Cloning the repo is required even when pulling the pre-built image. The repo provides the ./neurico CLI, config files, templates, and idea examples. The Docker image provides the runtime environment (Python, tools, LaTeX). At runtime, config and templates are mounted from your local clone into the container, so you can customize them without rebuilding.

GPU support requires NVIDIA Container Toolkit:

sudo apt install nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Native Installation

For users who prefer running directly on their system.

curl -LsSf https://astral.sh/uv/install.sh | sh   # Install uv
git clone https://github.com/ChicagoHAI/neurico
cd neurico
uv sync
cp .env.example .env   # Edit: add your API keys
claude   # Login to your AI CLI

Configuration

CLI Authentication

Claude Code, Codex, and Gemini CLIs use OAuth login (not API keys). Login once on your host machine:

claude    # or: codex, gemini

In Docker mode, credentials are automatically mounted into containers.

Environment Variables (.env)

The easiest way to configure is the interactive menu:

./neurico config

Or copy .env.example to .env and edit manually. Here's what each variable does:

GitHub — token required; org optional (uses personal account if empty)

Paper Finder — OPENAI_API_KEY + S2_API_KEY required for full paper-finder; COHERE_API_KEY optional (improves ranking)

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

Workspace Configuration

Research workspaces are created in the directory specified by config/workspace.yaml.

Default: workspace/ in the project root (already gitignored).

To customize: Copy config/workspace.yaml.example to config/workspace.yaml and edit parent_dir:

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

Customizing Templates and Skills

Templates in templates/ control agent behavior. In Docker mode, these are mounted from the host, so you can edit them without rebuilding:

See ARCHITECTURE_AND_ROADMAP.md for details on the template system.

Usage

Fetch from IdeaHub (Easiest)

Browse ideas at IdeaHub, then fetch and run:

# Docker
./neurico fetch <ideahub_url> --submit --run --provider claude --write-paper --full-permissions

# Native
uv run python src/cli/fetch_from_ideahub.py <ideahub_url> --submit --run --provider claude --write-paper --full-permissions

This one command: fetches the idea, converts it to YAML, submits it, creates a GitHub repo, runs the research agent, and writes a LaTeX paper.

You can also break it into steps:

./neurico fetch <url>             # Just fetch and convert to YAML
./neurico fetch <url> --submit    # Fetch, convert, and submit (creates GitHub repo)

Submit Your Own Idea

Write an idea YAML (see examples in ideas/examples/) and submit:

# Docker
./neurico submit ideas/examples/ml_regularization_test.yaml
./neurico run <idea_id> --provider claude --full-permissions

# Native
uv run python src/cli/submit.py ideas/examples/ml_regularization_test.yaml
uv run python src/core/runner.py <idea_id> --provider claude --full-permissions

Run Options

Other Commands

./neurico config      # Configure API keys and settings
./neurico shell       # Interactive shell inside the container
./neurico login       # Login to CLI tools inside the container
./neurico help        # Show all commands

flowchart LR
    subgraph Input
        A[Research Idea<br/>YAML] --> B[Submit CLI]
        C[IdeaHub URL] --> B
    end

    subgraph Processing
        B --> D[GitHub Repo<br/>Created]
        D --> E[Research Agent]
        E --> F[Literature Review]
        E --> G[Experiment Design]
        E --> H[Code Execution]
    end

    subgraph Output
        F --> I[Documentation]
        G --> I
        H --> I
        I --> J[Notebooks]
        I --> K[Results & Plots]
        I --> L[GitHub Push]
    end

ideas/
  submitted/      <- New research ideas
  in_progress/    <- Currently executing
  completed/      <- Finished research

workspace/<repo-name>/
  .claude/skills/ <- Claude Code skills (paper-finder, literature-review, etc.)
  src/            <- Python scripts for experiments (default mode)
  results/        <- Metrics, plots, models
  logs/           <- Execution logs and transcripts
  artifacts/      <- Models, checkpoints
  notebooks/      <- Jupyter notebooks (only with --use-scribe)
  paper_draft/    <- LaTeX paper output (only with --write-paper)
  .neurico/ <- Original idea spec

idea:
  title: "Do LLMs understand causality?"
  domain: artificial_intelligence
  hypothesis: "LLMs can distinguish causal from correlational relationships"
  # That's it! Agent handles the rest

idea:
  title: "Clear, descriptive title"
  domain: machine_learning
  hypothesis: "Specific, testable hypothesis"

  background:
    description: "Context and motivation"
    papers:
      - url: "https://arxiv.org/..."
        description: "Why this paper is relevant"
    datasets:
      - name: "Dataset name"
        source: "Where to get it"

  methodology:
    approach: "High-level strategy"
    steps: ["Step 1", "Step 2"]
    baselines: ["Baseline 1", "Baseline 2"]
    metrics: ["Metric 1", "Metric 2"]

  constraints:
    compute: gpu_required
    time_limit: 3600

Documentation

• docs/WORKFLOW.md - Complete workflow guide
• docs/IDEAHUB_INTEGRATION.md - IdeaHub integration
• ARCHITECTURE_AND_ROADMAP.md - Architecture, template system, and roadmap
• docs/GITHUB_INTEGRATION.md - GitHub setup and usage
• config/domains.yaml - Research domain definitions (single source of truth)
• templates/README.md - Prompt template system overview
• ideas/schema.yaml - Full specification schema
• ideas/examples/ - Example research ideas

Contributing

Contributions welcome! Areas of interest:

• New domain templates (biology, chemistry, social science, etc.)
• Additional evaluation criteria
• Integration with experiment trackers
• Web interface
• Multi-agent collaboration features

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 file

./neurico fetch https://hypogenic.ai/ideahub/idea/YOUR_IDEA_ID \
    --submit --run --provider claude --full-permissions