Features β’ Quick Start β’ Project Structure β’ Skills β’ Acknowledgments
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.
- [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.
- 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
Show supported dataset table
| Dataset | Supported Modalities | Additional Data | Cohort Scale | Official Link |
|---|---|---|---|---|
| ABCD Study | T1w; T2w; dMRI; rs-fMRI; task-fMRI | Physical and mental health; substance use; culture/environment; neurocognition; biological data | Target cohort of ~11,500 children; full cohort releases through the NIMH Data Archive | https://abcdstudy.org/ |
| ABIDE | T1w; rs-fMRI | ASD/control phenotypic data | 1,112 datasets from 17 international sites | https://fcon_1000.projects.nitrc.org/indi/abide/ |
| ADHD-200 | T1w; rs-fMRI | Diagnostic status; ADHD symptom measures; demographics; medication history; QC measures | 776 participants/datasets across 8 imaging sites | https://fcon_1000.projects.nitrc.org/indi/adhd200/ |
| AIBL | T1w; PET (PiB, FDG, tau) | Cognitive assessments; blood biomarkers; lifestyle and demographic data; APOE genotype | ~1,100+ participants (healthy controls, MCI, AD) | https://aibl.csiro.au/ |
| AOMIC | T1w; rs-fMRI; task-fMRI | Personality traits (Big Five); fluid intelligence; demographic data | ~1,000+ participants | https://nilab-uva.github.io/AOMIC.github.io/ |
| ADNI | T1w; T2w; FLAIR; dMRI; rs-fMRI; PET | Genetics/omics data; clinical and cognitive assessments | ~2,000+ participants across ADNI phases | https://adni.loni.usc.edu/ |
| BOLD5000 | T1w; task-fMRI | Visual image stimuli; category and image metadata | 4 participants with 5,000-image visual fMRI sessions | https://bold5000-dataset.github.io/ |
| Cam-CAN | T1w; T2*w; rs-fMRI; task-fMRI; MEG | Cognitive, sensory, and health measures across the adult lifespan | ~700 participants ages 18-88 | https://www.cam-can.org/ |
| COBRE | T1w; rs-fMRI | Demographics; handedness; diagnostic information | 147 participants: 72 schizophrenia patients and 75 healthy controls | https://fcon_1000.projects.nitrc.org/indi/retro/cobre.html |
| DMT-HAR-MED | rs-fMRI | Psychedelic intervention conditions; behavioral and physiological measures | 40 participants in OpenNeuro ds006644 | https://openneuro.org/datasets/ds006644/versions/1.0.1 |
| HBN | T1w; T2w; dMRI; rs-fMRI; task-fMRI; EEG | Psychiatric, behavioral, cognitive, lifestyle, genetics, actigraphy | ~3,900+ released participants; target resource of at least 10,000 ages 5-21 | https://fcon_1000.projects.nitrc.org/indi/cmi_healthy_brain_network/ |
| HCP Aging | T1w; T2w; dMRI; rs-fMRI; task-fMRI | Behavioral, cognitive, health, and demographic measures | ~700+ adults ages 36-100 | https://www.humanconnectome.org/study/hcp-lifespan-aging |
| HCP Development | T1w; T2w; dMRI; rs-fMRI; task-fMRI | Behavioral, cognitive, health, and demographic measures | ~600+ children and adolescents ages 5-21 | https://www.humanconnectome.org/study/hcp-lifespan-development |
| HCP Early Psychosis | T1w; T2w; dMRI; rs-fMRI; task-fMRI | Diagnostic, clinical, behavioral, and cognitive measures | ~250 early psychosis and control participants | https://www.humanconnectome.org/study/hcp-early-psychosis |
| HCP Young Adult | T1w; T2w; dMRI; rs-fMRI; task-fMRI | Behavioral and cognitive measures | ~1,200 young adult participants | https://www.humanconnectome.org/study/hcp-young-adult |
| IXI | T1w; T2w; MRA | Healthy brain MRI from three London hospitals | ~600 subjects | https://brain-development.org/ixi-dataset/ |
| MS Challenge | T1w; T2w; FLAIR; PD | Expert manual lesion segmentations for MS benchmarking | 5 MS patients with multiple longitudinal timepoints | https://smart-stats-tools.org/lesion-challenge |
| MND | rs-fMRI; task-fMRI | Motor neuron disease diagnosis and clinical measures | 59 participants in OpenNeuro ds005874 | https://openneuro.org/datasets/ds005874/versions/1.1.0 |
| Natural Scenes Dataset | T1w; task-fMRI | Natural image stimuli; behavioral responses; image annotations | 8 participants with dense repeated visual fMRI | https://naturalscenesdataset.org/ |
| NIFD | T1w; fMRI; DTI; PET | FTD clinical and cognitive data; UCSF Memory and Aging Center | Frontotemporal dementia and related disorders cohorts | https://ida.loni.usc.edu/ |
| OASIS | T1w; PET (PiB) | Clinical and cognitive assessments; dementia diagnosis; demographic data | Cross-sectional (400+) and longitudinal (150+) participants ages 18-96 | https://www.oasis-brains.org/ |
| PNC | T1w; dMRI; ASL; rs-fMRI; task-fMRI | Genotyping; clinical and neuropsychiatric assessment; Computerized Neurocognitive Battery | >9,500 youth cohort; 1,445 participants with neuroimaging | https://www.med.upenn.edu/bbl/philadelphianeurodevelopmentalcohort.html |
| PPMI | T1w; rs-fMRI; DAT-SPECT; PET | Clinical, genetic, biospecimen, and wearable sensor data for Parkinson's disease | ~2,000+ participants across 30+ clinical sites worldwide | https://www.ppmi-info.org/ |
| REST-meta-MDD | rs-fMRI | MDD diagnosis; clinical and demographic measures | 2,428 participants across 25 cohorts | http://rfmri.org/REST-meta-MDD |
| SEED-IV | EEG | Emotion labels across four affective categories; trial-level session metadata | 15 subjects across 3 sessions for emotion decoding benchmarks | https://bcmi.sjtu.edu.cn/home/seed/ |
| SEED-VIG | EEG | Vigilance/fatigue labels; continuous alertness annotations; behavioral metadata | 23 subjects in sustained-attention driving-style vigilance recordings | https://bcmi.sjtu.edu.cn/home/seed/ |
| TCP | rs-fMRI | Psychiatric diagnostic interviews; cognitive and clinical assessments | 245 transdiagnostic participants | https://openneuro.org/datasets/ds004215 |
| UCLA CNP | T1w; dMRI; rs-fMRI; task-fMRI | Diagnostic groups; neuropsychological and phenotypic assessments | 272 participants in OpenNeuro ds000030 | https://openneuro.org/datasets/ds000030 |
| UK Biobank | T1w; T2w; FLAIR; dMRI; rs-fMRI; task-fMRI | Genotype/genomic data; questionnaires; hospital records; environmental data; sociodemographic data; physical measures | ~50,000 participants with multimodal imaging data | https://www.ukbiobank.ac.uk/ |
- 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
- 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
- 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, andSOUL.mdcan 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.jsonand can be re-enabled if needed.
Download the latest Windows or macOS client from the GitHub Releases page.
- Windows: use
NeuroClaw Setup 0.2.1.exefor normal installation. The portable.exeis also available, but may take longer to start because it extracts the app first. - macOS: use the
.dmgor.zipbuild 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.
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 --webThen 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.0Settings are saved to neuroclaw_environment.json. API keys can be passed at runtime with --api-key or provided through the configured provider environment variable.
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 codexCommon targets:
| Host agent | Install command |
|---|---|
| Codex | python installer/install_agent_integration.py --target codex |
| Claude Code | python installer/install_agent_integration.py --target claude-code |
| Cursor | python installer/install_agent_integration.py --target cursor --scope project |
| Multiple agents | python installer/install_agent_integration.py --target all |
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.
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 fromskills/no-skills: the baseline run without skillswith-skills+no-skillspaired comparison: enable--benchmark-compare-skillsto 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-benchmarkTo speed up scoring on larger runs:
python core/agent/main.py --score-benchmark --score-workers 8Web benchmark mode
python core/agent/main.py --web --benchmarkCLI benchmark batch runner
python core/agent/main.py --benchmarkTo run the paired skill comparison in CLI mode:
python core/agent/main.py --benchmark --benchmark-compare-skillsIn CLI benchmark mode, NeuroClaw will ask for:
- the benchmark directory path
- the benchmark model name
Then it will:
- read all
task.mdfiles 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/<model_name>/, 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.
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
Tip: Click the βΉοΈ icon on any skill card in the Web UI to view expanded documentation, usage examples, and recent execution logs.
| Skill | Function | Status |
|---|---|---|
dcm2nii |
DICOM β NIfTI conversion with metadata support | β |
nii2dcm |
NIfTI β DICOM conversion for clinical interoperability | β |
git-essentials |
Core Git commands for collaboration | β |
git-workflows |
Advanced Git workflows (rebase/worktree/bisect) | β |
multi-search-engine |
Multi-engine web search without API keys | β |
conda-env-manager |
Conda environment lifecycle management | β |
docker-env-manager |
Docker environment management | β |
dependency-planner |
Dependency planning and safe installation workflow | β |
claw-shell |
Safe shell execution gateway via dedicated session | β |
overleaf-skill |
Overleaf sync and collaborative manuscript operations | β |
academic-research-hub |
Multi-source academic search and paper retrieval | β |
bids-organizer |
Base skill for organizing raw data into BIDS structure | β |
beautiful-log |
Export clean User/NeuroClaw dialogue into beautiful HTML logs | β |
knowledge-graph-builder |
Build domain knowledge graphs from literature and databases | β |
skill-updater |
Skill updater and management utilities | β |
| Skill | Function | Status |
|---|---|---|
research-idea |
Brainstorms and generates research ideas from literature | β |
method-design |
Formalizes network architecture and derives theoretical components | β |
experiment-controller |
Finds and executes reproducible research experiments | β |
paper-writing |
Generates hierarchical manuscript drafts from IDEA/METHOD/EXPERIMENT | β |
Subagent in NeuroClaw includes four categories: tool, model, dataset, and modality.
| Skill | Function | Status |
|---|---|---|
brain-visualization |
Publication-ready figures and 3D assets (connectomes, atlas summaries, FreeSurfer PLY) | β |
harmonization-tool |
Cross-site / cross-scanner feature harmonization (ComBat, ComBat-GAM, CovBat, site-as-covariate) with site-stratified and leave-site-out splitters; required for honest mega-analysis across multi-site cohorts | β |
harness-core |
Core harness SDK: verification, checkpointing, drift detection, audit logging | β |
mne-eeg-tool |
Base-layer MNE-Python implementation for EEG | β |
fsl-tool |
FSL-based sMRI/fMRI/DWI processing utilities | β |
fmriprep-tool |
fMRIPrep pipeline wrapper and execution | β |
qsiprep-tool |
qsiPrep pipeline wrapper for diffusion MRI | β |
hcppipeline-tool |
HCP-style processing pipeline utilities | β |
dipy-tool |
Diffusion MRI processing via DIPY | β |
nibabel-skill |
Low-level neuroimaging I/O and geometry handling (NIfTI, affine, FreeSurfer I/O) | β |
nilearn-tool |
Fast neuroimaging feature extraction and decoding prep | β |
conn-tool |
Functional connectivity computation and analysis | β |
freesurfer-tool |
FreeSurfer-based MRI processing and segmentation | β |
| Skill | Function | Status |
|---|---|---|
run_models |
Model registry and model execution orchestration | β |
wmh-segmentation |
White matter hyperintensity segmentation (MARS-WMH nnU-Net) | β |
brain_gnn |
BrainGNN: graph neural network for fMRI classification | β |
bnt |
BrainNetworkTransformer: dense FC Transformer with DEC pooling for phenotype prediction | β |
combraintf |
Com-BrainTF: community-aware two-level Transformer over dense FC matrices | β |
ibgnn |
IBGNN: interpretable PyG-based GNN with MLP message function and edge-mask explainer | β |
lggnn |
LG-GNN: PyG-based GNN with Self-Attention Brain Pooling and mutual-information regularization | β |
fm_app |
FM-APP: multi-stage phenotype prediction with fMRI+sMRI | β |
neurostorm |
NeuroStorm: neuroimaging foundation model | β |
glm |
Classical first-level and second-level GLM for task-fMRI activation and group inference | β |
ica |
Resting-state network decomposition via independent component analysis | β |
dictlearning |
Sparse resting-state network decomposition via dictionary learning | β |
svm |
Classical neuroimaging disease classification with ROI/tabular features | β |
spacenet |
Voxel-wise neuroimaging disease classification with sparse coefficient maps | β |
kmeans |
Brain parcellation via K-means clustering | β |
hierarchical |
Multi-scale brain parcellation via hierarchical clustering | β |
filtering |
Temporal filtering for neuroimaging signal denoising | β |
detrending |
Temporal drift removal for neuroimaging signal denoising | β |
| Skill | Function | Status |
|---|---|---|
abide-skill |
ABIDE dataset download, BIDS staging, and sMRI/rs-fMRI processing | β |
aibl-skill |
AIBL dataset access, BIDS staging, and sMRI/PET processing | β |
abcd-skill |
ABCD Study dataset download, BIDS staging, and multimodal processing | β |
adhd200-skill |
ADHD-200 dataset download, BIDS staging, and sMRI/rs-fMRI processing | β |
adni-skill |
ADNI dataset automated processing workflow | β |
aomic-skill |
AOMIC dataset validation, BIDS staging, and sMRI/rs-fMRI/task-fMRI processing | β |
bold5000-skill |
BOLD5000 dataset BIDS validation and visual task-fMRI processing | β |
camcan-skill |
Cam-CAN dataset BIDS validation, multimodal sMRI/rs-fMRI/task-fMRI/dMRI processing | β |
cobre-skill |
COBRE dataset BIDS staging and schizophrenia-control fMRI processing | β |
dmt-har-med-skill |
DMT-HAR-MED dataset BIDS validation and psychedelic rs-fMRI processing | β |
hbn-skill |
HBN dataset download, BIDS staging, and multimodal sMRI/fMRI/dMRI/EEG processing | β |
hcpa-skill |
HCP Aging dataset download, BIDS staging, and multimodal sMRI/fMRI/dMRI processing | β |
hcpd-skill |
HCP Development dataset download, BIDS staging, and multimodal sMRI/fMRI/dMRI processing | β |
hcpep-skill |
HCP Early Psychosis dataset download, BIDS staging, and multimodal sMRI/fMRI/dMRI processing | β |
hcpya-skill |
HCP Young Adult (HCP1200) dataset download, BIDS staging, and multimodal sMRI/fMRI/dMRI processing | β |
ixi-skill |
IXI dataset BIDS validation and multimodal sMRI/MRA/dMRI processing | β |
mnd-skill |
MND dataset BIDS validation, rs-fMRI/task-fMRI processing, and phenotype extraction | β |
mschallenge-skill |
MS Lesion Challenge BIDS validation, lesion analysis, and longitudinal tracking | β |
nsd-skill |
Natural Scenes Dataset BIDS validation, task-fMRI processing, and COCO stimulus extraction | β |
nifd-skill |
NIFD dataset BIDS validation, multimodal sMRI/rs-fMRI/dMRI processing for frontotemporal dementia | β |
oasis-skill |
OASIS dataset BIDS validation, sMRI processing, and phenotype extraction for aging/AD research | β |
pnc-skill |
PNC dataset BIDS validation, multimodal sMRI/rs-fMRI/task-fMRI/dMRI processing for developmental studies | β |
ppmi-skill |
PPMI dataset BIDS validation, multimodal sMRI/rs-fMRI/dMRI processing for Parkinson's disease | β |
rest-mneta-mdd-skill |
REST-meta-MDD multi-site rs-fMRI processing, site harmonization, and depression phenotype extraction | β |
seed-iv-skill |
SEED-IV EEG emotion recognition (4 emotions), feature extraction, and classification | β |
seed-vig-skill |
SEED-VIG EEG vigilance/fatigue detection, feature extraction, and drowsiness classification | β |
tcp-skill |
Transdiagnostic Connectome Project BIDS validation, multimodal sMRI/rs-fMRI/dMRI processing | β |
ucla-cnp-skill |
UCLA CNP BIDS validation, multimodal sMRI/task-fMRI/dMRI processing, multi-disorder phenotyping | β |
ukb-skill |
UKB brain imaging automated processing workflow | β |
| Skill | Function | Status |
|---|---|---|
eeg-skill |
EEG preprocessing and feature extraction workflows | β |
fmri-skill |
Functional MRI preprocessing and analysis workflows | β |
smri-skill |
Structural MRI preprocessing and analysis workflows | β |
dwi-skill |
Diffusion MRI preprocessing and analysis workflows | β |
pet-skill |
PET imaging workflows (SUVR computation, reference regions, PVC) | β |
asl-skill |
ASL perfusion MRI workflows (CBF quantification, Buxton model) | β |
meg-skill |
MEG processing workflows (source localization, time-frequency, connectivity) | β |
Legend: β Implemented | ποΈ In Development | β³ Planned
Thanks to:
- OpenClaw
- Hermes
- Claude Code
- Karcen/rs-fMRI-Pipeline-Tutorial
- nature-skills
- Open-source neuroscience tools community (MNE-Python, FreeSurfer, FSL, etc.)




