cuhk-aim-group/neuroclaw

📖 Overview

NeuroClaw is a research assistant for executable and reproducible neuroimaging research. Its core strength is neuroimaging dataset and model adaptation: turning raw scans into usable inputs quickly, and enabling medical practitioners to run deep learning models with minimal setup.

Neuroimaging datasets demand specialized preprocessing, and preprocessing quality directly determines model validity. Many workflows assume curated datasets, while MedicalClaw provides limited automation for open-source model execution (primarily large projects like TimesFM and AlphaFold), leaving users to spend significant time on environment configuration.

NeuroClaw prioritizes data processing and model configuration/execution. It ships with independent GUI and CLI interfaces for day-to-day use, and can also be installed as a reusable skill library inside agent projects such as OpenClaw, Hermes, and Claude Code.

---

🚀 Updates

• [2026.06.20]: NeuroClaw now provides Windows and macOS desktop clients, while Linux remains supported through the repository and command-line/web workflows.
• [2026.05.23]: NeuroBench now covers both data processing and model training/evaluation.
• [2026.05.20]: 7 atoms × 15 canonical tasks + 4 mediation chains in neurooracle.atoms.
• [2026.05.15]: NeuroOracle launched: knowledge-graph explorer plus hypothesis engine with live demo at https://huggingface.co/spaces/zxcvb20001/NeuroOracle.
• [2026.05.06]: Added 19 dataset and modality skills with companion scripts; all 86 skills enforce unified metadata (layer, skill_type, dependencies); skill_loader DAG validation ensures dependency graph correctness.
• [2026.04.28]: Our technical report is now available on arXiv: https://arxiv.org/abs/2604.24696
• [2026.04.22]: v1.0 released. Stable release with improvements and full documentation.
• [2026.04.17]: Our project homepage is now live. Welcome to visit: https://cuhk-aim-group.github.io/NeuroClaw/
• [2026.04.08]: NeuroBench released for multi-agent neuroimaging workflow evaluation.
• [2026.04.02]: v0.1 released with complete NeuroClaw framework and core functionality.

✨ Key Features

🔄 Data-Aware Orchestration

• Dataset-Context Planning: Organize capabilities around dataset structure, metadata, and workflow stage instead of simply “which tool to call”
• Automatic Skill Recommendation: Users specify the target dataset, and NeuroClaw recommends relevant skills and executable workflows
• Preprocessing Constraint Awareness: Dataset-specific modality availability and preprocessing requirements are considered during orchestration

Supported Dataset Overview

Access is not equivalent to anonymous download. See the verified access matrix for registration, DUA, review, fee, and current availability details.

🎯 Executability and Reproducibility

• Automatic Dependency Management: No manual installation needed; the system detects and resolves dependencies
• True Model Execution: Beyond sharing docs, it guides and executes model reproduction
• Environment Isolation: Virtual environments and containerization avoid system pollution
• Verifiable Processes: Complete logging and result tracking
• Shadow Checkpoints: Git-based filesystem snapshots for rollback and diff comparison without polluting the project repository
• Subagent Orchestration: Spawns specialized subagents (biostatistician, clinical neuroscientist, methodology expert) for multi-perspective task execution
• Reflective Learning: Automatic reflection on tool failures and task completion, with persistent memory for cross-session learning

🧠 End-to-End Research Coverage

• Literature Review: arXiv search, PubMed retrieval, academic resource integration
• Experiment Design: Scientific literature analysis, methodology evaluation, research proposal generation
• Data Processing: Multi-format conversion (DICOM ↔ NIfTI), automated preprocessing pipelines
• Model Execution: Run published research models, deep learning framework integration
• Result Visualization: Scientific data visualization, statistical chart generation
• Paper Writing: Auto-generated drafts, format standardization

🤝 Flexible Integration

• NeuroClaw works as a standalone research assistant with its own GUI and CLI, so researchers can use it directly without depending on another host project.
• skills/, materials/, USER.md, and SOUL.md can also be installed as a reusable skill library in existing agent systems such as OpenClaw, Hermes, and Claude Code.
• The bundled core/ engine provides an integrated agent loop, skill loader, and tool runtime for standalone deployments.
• Non-neuroscience connectors (WhatsApp, Telegram, Slack, calendar, e-commerce, SaaS auth) are disabled by default via core/config/features.json and can be re-enabled if needed.

---

🚀 Quick Start

Option 1. Desktop Client (recommended)

Download the latest Windows or macOS client from the GitHub Releases page.

• Windows: use NeuroClaw Setup 0.2.1.exe for normal installation. The portable .exe is also available, but may take longer to start because it extracts the app first.
• macOS: use the .dmg or .zip build from the release assets.
• Open Settings to configure the model endpoint, runtime mode, Python path, FSL path, proxy, language, and text size.
• Open NeuroOracle from the sidebar. If the graph file is missing, the client can download it from Hugging Face.

Linux remains supported through the source repository, command-line workflow, and web interface.

Option 2. Run from Source

Requirements: Python >= 3.10 and Git. Conda/Mamba, CUDA/GPU tools, FSL, FreeSurfer, and dcm2niix are optional depending on the workflows you want to run.

git clone https://github.com/CUHK-AIM-Group/NeuroClaw.git
cd NeuroClaw
python installer/setup.py
python core/agent/main.py --web

Then open http://localhost:7080 in your browser.

Useful checks:

python installer/setup.py --check
python core/agent/main.py --web --port 8080 --host 0.0.0.0

Settings are saved to neuroclaw_environment.json. API keys can be passed at runtime with --api-key or provided through the configured provider environment variable.

Option 3. Install as a Host-Agent Skill

Use this path if you want Codex, Claude Code, Cursor, or another coding agent to call NeuroClaw as a neuroimaging skill library.

git clone https://github.com/CUHK-AIM-Group/NeuroClaw.git
cd NeuroClaw
python installer/install_agent_integration.py --target codex

Common targets:

After installation, ask the host agent to use NeuroClaw or enter NeuroClaw mode for neuroimaging, NeuroOracle, NeuroBench, and autoresearch tasks.

Note: We provide benchmark run results and per-model outputs under materials/benchmark_results/. These artifacts can be used as practical references when running NeuroClaw benchmarks or reproducing model outputs.

Benchmark Evaluation

NeuroBench tasks live under neurobench/, and each task directory contains a task.md instruction file.

NeuroBench currently accepts these benchmark configurations:

• with-skills: the agent can use the skills loaded from skills/
• no-skills: the baseline run without skills
• with-skills + no-skills paired comparison: enable --benchmark-compare-skills to run both variants for the same task set

Benchmark scoring is handled separately with --score-benchmark: it reads reports in output/, applies a GPT-5.4 weighted rubric, and generates numeric scores for planning completeness, tool/skill reasonableness, and command/code correctness. For fairness, each task case is scored in one batch across all comparable models to reduce scoring-standard drift. Skill-call counts are recorded separately and used for efficiency analysis.

To score existing benchmark reports:

python core/agent/main.py --score-benchmark

To speed up scoring on larger runs:

python core/agent/main.py --score-benchmark --score-workers 8

Web benchmark mode

python core/agent/main.py --web --benchmark

CLI benchmark batch runner

python core/agent/main.py --benchmark

To run the paired skill comparison in CLI mode:

python core/agent/main.py --benchmark --benchmark-compare-skills

In CLI benchmark mode, NeuroClaw will ask for:

• the benchmark directory path
• the benchmark model name

Then it will:

• read all task.md files recursively from that directory
• sort tasks alphabetically by task folder name
• run tasks one by one without asking for intermediate confirmation
• print progress in the terminal only
• save reports under output//, with one markdown report per case and run

The benchmark reports include the solution thinking, skills used, skill-call counts, and the commands or code that were used or suggested.

---

📁 Project Structure

NeuroClaw/
├── README.md / README_zh.md        # Project documentation
├── USER.md / SOUL.md               # User preferences and agent behavior guidelines
│
├── core/                           # Standalone NeuroClaw engine
│   ├── agent/                      # CLI/Web agent entry points
│   ├── web/                        # FastAPI Web UI
│   ├── skill_loader/               # Reads skills/*/SKILL.md
│   └── config/                     # Feature toggles and runtime settings
│
├── installer/                      # Setup wizard and host-agent integration installer
│   ├── setup.py
│   ├── config_wizard.py
│   └── install_agent_integration.py
│
├── skills/                         # Skill library
│   ├── base skills                 # Environment, search, BIDS, Git, conversion
│   ├── interface skills            # Research idea, method design, experiments, writing
│   └── subagent skills             # Tool, model, dataset, and modality workflows
│
├── models/                         # Brain model adapters and training/evaluation scripts
├── neurooracle/                    # Knowledge graph and autoresearch pipeline
│
├── neurobench/                     # NeuroBench evaluation tasks (T01-T120)
│
├── docs/                           # Project website pages
├── materials/                      # Research materials and benchmark outputs
│
└── LICENSE                         # License

---

🛠️ Skill Quick Reference

Tip: Click the ℹ️ icon on any skill card in the Web UI to view expanded documentation, usage examples, and recent execution logs.

Base Layer

Interface Layer (Task Orchestration)

Subagent Layer

Subagent in NeuroClaw includes four categories: tool, model, dataset, and modality.

Tool

Model

Workflow

Dataset

Modality

Legend: ✅ Implemented | 🏗️ In Development | ⏳ Planned

---

🙏 Acknowledgments

Thanks to:

• OpenClaw
• Hermes
• Claude Code
• Karcen/rs-fMRI-Pipeline-Tutorial
• nature-skills
• Open-source neuroscience tools community (MNE-Python, FreeSurfer, FSL, etc.)