NeuriCo

Autonomous research framework that orchestrates AI agents (Claude Code, Codex, Gemini) to design, execute, analyze, and document scientific experiments. Take...

Security Scan

The skill's declared purpose (autonomous research: design/execute/analyze experiments and push results to GitHub) aligns with the instructions and required resources, but there is limited visibility (no code included in the skill bundle) and it depends on external artifacts (GitHub repo, Docker image and CLIs) that you should verify before use.

Purpose & Capability

Name/description promise (autonomous research pipeline producing code, results, LaTeX, GitHub repo) matches the SKILL.md instructions which describe cloning the project, using Docker or native Python, logging into AI provider CLIs, and optionally providing GitHub and other API keys. Required resources suggested (GITHUB_TOKEN, AI CLIs, optional LLM/data service keys) are appropriate for the stated functionality.

Instruction Scope

SKILL.md instructs the operator to clone a GitHub repository, pull a Docker image (ghcr.io/chicagohai/neurico:latest), run a local setup script, log into provider CLIs (Claude/Codex/Gemini), and optionally place API keys into a .env. These steps are consistent with the skill's purpose but they require host-level operations (Docker, OAuth CLI logins, storing tokens) and will cause code and experiments to run on your machine or inside a container. Because the skill bundle contains only documentation (no code), the actual runtime behavior depends entirely on the external repository and Docker image; you should inspect those sources before running.

Install Mechanism

The skill itself has no install spec or embedded code (instruction-only). The README recommends cloning a GitHub repository and pulling a GitHub Container Registry image. Those are normal for this use-case. No obscure download URLs, shorteners, or embedded binary payloads are present in the provided SKILL.md; the risk surface is the external repo and container referenced.

Credentials

The skill declares no required env vars in the bundle, but SKILL.md recommends a GitHub token (repo scope) and lists several optional API keys (OPENAI_API_KEY, S2_API_KEY, HF_TOKEN, WANDB_API_KEY, etc.) that are plausible for added features. Requesting a full-scoped GitHub token is proportionate to auto-creating and pushing repos but you should prefer least-privilege (use a token with only the necessary repo scopes, or use --no-github). Optional keys are reasonable for enhanced functionality, but you should not provide unrelated secrets.

Persistence & Privilege

Skill flags show always:false and agent invocation is allowed (default). The skill does not request permanent platform-level privileges in the bundle. However, runtime setup will ask you to store credentials (GitHub token, CLI OAuth) and possibly write a .env; those are normal for tooling but you should manage tokens carefully and run in an isolated environment if unsure.

Assessment

This skill appears coherent with its stated goal, but the bundle contains only documentation and relies on an external GitHub repository and a Docker image. Before using it: 1) Inspect the referenced GitHub repo (https://github.com/ChicagoHAI/neurico) and the Dockerfile/image (ghcr.io/chicagohai/neurico) to ensure they are legitimate and contain no unexpected scripts. 2) Prefer running the Docker image (container isolation) rather than native install. 3) Create and use least-privilege GitHub tokens (avoid full account-scoped tokens; use repo-scoped tokens or run with --no-github if you don't want pushes). 4) Avoid supplying unrelated secrets; only provide API keys you understand and need. 5) If you cannot verify the external sources or you lack isolation, do not run the setup scripts or the container on sensitive hosts. Additional information that would increase confidence: a verifiable upstream repository/maintainer identity, signed/reproducible container image, or included code files for local review.

Autonomous AI research framework. Idea in, paper out.

Quick Reference

What it does	Takes a research idea (YAML) and autonomously runs the full research lifecycle: literature review, experiment design, code execution, analysis, paper writing, GitHub push
Input	YAML file with 3 required fields: title, domain, hypothesis
Output	Code (src/), results & plots (results/), LaTeX paper (paper_draft/), GitHub repo
Providers	Claude Code, Codex, Gemini (OAuth login, not API keys)
Install	git clone https://github.com/ChicagoHAI/neurico && cd neurico && ./neurico setup
Source	github.com/ChicagoHAI/neurico — Chicago Human+AI Lab (ChicagoHAI), University of Chicago
License	Apache 2.0

Requirements

Minimal (one of)

Option	What you need
Docker (recommended)	git + docker
Native	git + python>=3.10 + uv

Resource

Access to at least one AI coding CLI (OAuth login required):

• Claude Code (recommended)
• Codex
• Gemini CLI

Recommended

What	Why
GitHub token (classic, repo scope)	Auto-creates repos and pushes results. Create here

Optional API Keys

Key	Purpose
OPENAI_API_KEY	LLM-based repo naming, IdeaHub fetching, paper-finder
S2_API_KEY	Semantic Scholar literature search via paper-finder
OPENROUTER_KEY	Multi-model access during experiments
COHERE_API_KEY	Improves paper-finder ranking (~7% boost)
HF_TOKEN	Hugging Face private models/datasets
WANDB_API_KEY	Weights & Biases experiment tracking

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

Installation

Docker (recommended)

The Docker image is a pre-configured environment with Python, Node.js, AI coding CLIs (Claude Code, Codex, Gemini), and a full LaTeX installation for paper compilation -- so you don't have to install any of these yourself. All experiments run inside this container; nothing is installed on your host system beyond the cloned repo. The image is built from the open-source Dockerfile and hosted on GitHub Container Registry.

git clone https://github.com/ChicagoHAI/neurico && cd neurico
./neurico setup     # pulls Docker image, configures API keys, walks through CLI login

Or step by step:

git clone https://github.com/ChicagoHAI/neurico && cd neurico
docker pull ghcr.io/chicagohai/neurico:latest
docker tag ghcr.io/chicagohai/neurico:latest chicagohai/neurico:latest
./neurico config    # configure API keys
claude              # login to AI CLI (one-time, on host)

Native

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

Invocation

Fastest: Fetch from IdeaHub and run

./neurico fetch <ideahub_url> --submit --run --provider claude

Browse ideas at IdeaHub, copy the URL, and run the command above. NeuriCo fetches the idea, creates a GitHub repo, runs experiments, writes a paper, and pushes everything.

From a YAML file

./neurico submit path/to/idea.yaml
./neurico run <idea_id> --provider claude

Run options

Option	Description
--provider claude|gemini|codex	AI provider (default: claude)
--no-github	Run locally without GitHub integration
--write-paper	Generate LaTeX paper after experiments (default: on)
--paper-style neurips|icml|acl|ams	Paper format (default: neurips)
--private	Create private GitHub repository

Input Format

Only 3 fields required:

idea:
  title: "Do LLMs understand causality?"
  domain: artificial_intelligence
  hypothesis: "LLMs can distinguish causal from correlational relationships"

Optional fields: background (papers, datasets, code references), methodology (approach, steps, baselines, metrics), constraints (compute, time, memory, budget), expected_outputs, evaluation_criteria.

Full schema: ideas/schema.yaml

Output Format

workspace/<repo-name>/
  src/            # Python experiment code
  results/        # Metrics, plots, models
  paper_draft/    # LaTeX paper (with --write-paper)
  logs/           # Execution logs
  artifacts/      # Models, checkpoints
  .neurico/       # Original idea spec

Results are automatically pushed to the GitHub repo created during submission.

Supported Domains

Domain	Examples
Artificial Intelligence	LLM evaluation, prompt engineering, AI agents
Machine Learning	Training, evaluation, hyperparameter tuning
Data Science	EDA, statistical analysis, visualization
NLP	Language model experiments, text analysis
Computer Vision	Image processing, object detection
Reinforcement Learning	Agent training, policy evaluation
Systems	Performance benchmarking, optimization
Theory	Algorithmic analysis, proof verification
Scientific Computing	Simulations, numerical methods

Configuration

./neurico config      # Interactive API key configuration
./neurico setup       # Full setup wizard
./neurico shell       # Interactive shell inside container
./neurico help        # Show all commands

Environment variables go in .env (copy from .env.example). See README for details.

Security

• No secrets are uploaded. API keys and tokens stay local in your .env file and are never committed, pushed, or sent anywhere beyond the APIs they authenticate with. Sensitive environment variables are explicitly filtered out from all subprocess calls and sanitized from logs.
• Experiments run inside Docker. The container is isolated from your host system. The only host directories mounted are your config, templates, and workspace output folder.
• Open source. The entire codebase, including the Dockerfile and install script, is publicly auditable on GitHub.
• Built by ChicagoHAI — the Human+AI Lab at the University of Chicago.