Use this skill whenever the user wants to process structural MRI data (T1w, T2w, FLAIR, etc.) with FreeSurfer, especially for cortical/subcortical segmentation, surface reconstruction, parcellation, cortical thickness, volume statistics, or full recon-all pipeline. Triggers include: 'freesurfer', 'recon-all', 'segment MRI', 'FreeSurfer processing', 'cortical segmentation', 'subcortical segmentation', 'run recon-all', 'freesurfer T1', 'process brain MRI with freesurfer', 'aseg aparc', or any request to run FreeSurfer on NIfTI MRI data for research analysis.
FreeSurfer is the gold-standard open-source suite for automated reconstruction of the brain’s cortical surface from structural MRI, including skull-stripping, intensity normalization, Talairach registration, cortical parcellation (Desikan-Killiany / Destrieux atlases), subcortical segmentation (aseg), surface mesh generation, cortical thickness estimation, and statistics.
This skill serves as the NeuroClaw interface-layer wrapper for FreeSurfer and strictly follows the hierarchical design:
recon-all --version, $FREESURFER_HOME environment variable).dependency-planner to plan and (after user confirmation) install the latest stable FreeSurfer release + license setup.SUBJECTS_DIR, desired stages/flags (e.g. -all, -autorecon1..3, -T2, -FLAIR, -parallel).claw-shell skill (environment setup, recon-all invocation, logging, progress monitoring).Key design principle (2026 update): No direct subprocess.run() calls for long-running FreeSurfer commands. All shell execution is routed through claw-shell for centralized logging, timeout handling, real-time output streaming, and interruption safety.
Research use only.
| Task | Recommended recon-all flags / approach |
|---|---|
| Full pipeline (most common) | -all |
| Fast subcortical + basic surfaces | -autorecon1 -autorecon2 -autorecon3 |
| Cortical surfaces & parcellation | -autorecon2 -autorecon3 (after autorecon1 completed) |
| Improve pial surface with T2 | -T2 T2w.nii.gz |
| Use FLAIR for better segmentation | -FLAIR FLAIR.nii.gz |
| Enable multi-core acceleration | -parallel -openmp 8 (or match available cores) |
| Resume interrupted run | Omit -i and -all, specify stages only |
| Generate statistics only | -stats |
Installation is fully delegated to dependency-planner.
When FreeSurfer is not detected:
dependency-planner with request:dependency-planner handles download, package install, license placement$FREESURFER_HOME and recon-all availabilityPrerequisites:
dependency-planner (mandatory for installation)claw-shell (mandatory for command execution)-all)# freesurfer_processor.py
import argparse
import os
import sys
from pathlib import Path
from datetime import datetime
# In real NeuroClaw: these would be agent tool calls
def check_freesurfer_installed():
# Simulate check via claw-shell
# Real impl: call claw-shell with "recon-all --version"
return False, "FreeSurfer not found (simulation mode)"
def delegate_to_claw_shell(commands, purpose, log_tag):
print(f"[Delegating to claw-shell] Purpose: {purpose}")
print(f"Log tag: {log_tag}")
print("Commands to execute:")
for cmd in commands:
print(" " + cmd)
# Real implementation: agent/tool call to claw-shell
# e.g. tool_call("claw-shell", commands=commands, log_tag=log_tag, capture_output=True, timeout="24h")
def main():
parser = argparse.ArgumentParser(description="NeuroClaw FreeSurfer Processor")
parser.add_argument("--input-mri", required=True, help="Path to T1w (or other) NIfTI file")
parser.add_argument("--subjid", required=True, help="Subject ID (e.g. sub-001)")
parser.add_argument("--subjects-dir", required=True, help="Output SUBJECTS_DIR path")
parser.add_argument("--stages", default="all", help="all / autorecon1 / autorecon2 / autorecon3 / stats / comma-separated stages")
parser.add_argument("--extra-flags", default="", help="Additional flags, e.g. '-T2 T2.nii.gz -FLAIR FLAIR.nii.gz -parallel -openmp 12'")
parser.add_argument("--plan-only", action="store_true", help="Show plan without execution")
args = parser.parse_args()
installed, version_info = check_freesurfer_installed()
if not installed:
print("FreeSurfer not detected on system.")
print("→ Invoking dependency-planner to install FreeSurfer and set up license.")
print("Please complete the dependency-planner confirmation flow first.")
sys.exit(1)
print("FreeSurfer detected:", version_info)
subjects_dir = Path(args.subjects_dir).resolve()
print(f"\nProcessing plan for subject: {args.subjid}")
print(f"Input MRI : {args.input_mri}")
print(f"Output dir : {subjects_dir}")
print(f"Stages : {args.stages}")
if args.extra_flags:
print(f"Extra flags : {args.extra_flags}")
# Build shell commands
commands = []
# 1. Set environment
fs_home = "/usr/local/freesurfer" # typical default; adjust if needed
commands.append(f"export FREESURFER_HOME={fs_home}")
commands.append(f"source $FREESURFER_HOME/SetUpFreeSurfer.sh")
# 2. recon-all command
recon_cmd = [
"recon-all",
"-subjid", args.subjid,
"-i", args.input_mri
]
if args.stages == "all":
recon_cmd.append("-all")
elif "," in args.stages:
for stage in args.stages.split(","):
stage = stage.strip()
if stage:
recon_cmd.append(f"-{stage}")
else:
recon_cmd.append(f"-{args.stages}")
if args.extra_flags:
recon_cmd.extend(args.extra_flags.split())
# Recommend parallel execution if not disabled
if "-parallel" not in args.extra_flags and "-openmp" not in args.extra_flags:
recon_cmd.extend(["-parallel", "-openmp", "8"])
commands.append(" ".join(recon_cmd))
log_tag = f"freesurfer_{args.subjid}_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
print("\nExecution plan (to be run via claw-shell):")
for i, cmd in enumerate(commands, 1):
print(f"Step {i}: {cmd}")
print(f"\nEstimated runtime: 4–24 hours (full -all), 1–4 hours (segmentation stages only)")
print(f"Disk usage: ~2–5 GB per subject")
print(f"Logs will be captured by claw-shell under tag: {log_tag}")
if args.plan_only:
print("\nPlan-only mode — no execution performed.")
return
confirm = input("\nExecute now? Type YES to proceed: ").strip().upper()
if confirm != "YES":
print("Aborted by user.")
return
print("\nDelegating pipeline execution to claw-shell skill...")
delegate_to_claw_shell(
commands=commands,
purpose=f"FreeSurfer processing for subject {args.subjid} ({args.stages})",
log_tag=log_tag
)
print(f"→ Execution handed over to claw-shell.")
print(f"→ Check logs using tag: {log_tag}")
print(f"→ Final outputs will be in: {subjects_dir / args.subjid}")
if __name__ == "__main__":
main()
claw-shell (no direct subprocess calls for recon-all).-all pipeline is very long-running → claw-shell should support background/detached mode or long timeouts..nii or .nii.gz); convert DICOM first using dcm2nii skill.$SUBJECTS_DIR/<subjid>.dependency-planner).license.txt is already in place after dependency-planner run.recon-all, aseg, aparc, cortical thickness, surface reconstruction, or FreeSurfer statistics.dependency-planner → install FreeSurfer + licenseclaw-shell → safe execution of long-running shell commandsconda-env-manager → manage Python environment for post-processing FreeSurfer outputsOfficial site: https://surfer.nmr.mgh.harvard.edu
Latest stable release (as of 2026): FreeSurfer 8.1.0 or newer
License registration: https://surfer.nmr.mgh.harvard.edu/registration.html
Documentation: https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferWiki
Custom NeuroClaw skill created to integrate FreeSurfer safely into the hierarchical skill structure.
After FreeSurfer processing completes, this skill automatically invokes harness-core's VerificationRunner to validate output integrity:
Integrated verification checks:
from skills.harness_core import VerificationRunner, AuditLogger
verifier = VerificationRunner(task_type="freesurfer_processing")
# 1. Brain-extracted anatomy files
verifier.add_check("brain_extraction",
checker=lambda: verify_brain_extraction(subjects_dir, subjid),
severity="error"
)
# 2. Cortical surface files (white, pial)
verifier.add_check("surface_reconstruction",
checker=lambda: verify_surface_files(subjects_dir, subjid),
severity="error"
)
# 3. Cortical thickness bounds (1–4 mm range)
verifier.add_check("thickness_bounds",
checker=lambda: verify_cortical_thickness_range(subjects_dir, subjid),
severity="warning"
)
# 4. parcellation labels (aparc/aseg)
verifier.add_check("parcellation",
checker=lambda: verify_aparc_aseg(subjects_dir, subjid),
severity="error"
)
# 5. Statistics file completeness
verifier.add_check("statistics",
checker=lambda: verify_stats_files(subjects_dir, subjid),
severity="warning"
)
report = verifier.run(subjects_dir)
# Log verification results
logger = AuditLogger(log_file=f"{subjects_dir}/{subjid}/freesurfer_verification.jsonl")
logger.log_validation(
task_name="freesurfer_processing",
subject_id=subjid,
checks_passed=len([r for r in report.results if r.passed]),
total_checks=len(report.results)
)
Output: {SUBJECTS_DIR}/{subjid}/freesurfer_verification.jsonl (structured audit log with JSONL format)
Created At: 2026-03-19 20:00 HKT
Last Updated At: 2026-04-05 02:03 HKT
Author: chengwang9638:["$","$L41",null,{"content":"$42","frontMatter":{"name":"freesurfer-tool","description":"Use this skill whenever the user wants to process structural MRI data (T1w, T2w, FLAIR, etc.) with FreeSurfer, especially for cortical/subcortical segmentation, surface reconstruction, parcellation, cortical thickness, volume statistics, or full recon-all pipeline. Triggers include: 'freesurfer', 'recon-all', 'segment MRI', 'FreeSurfer processing', 'cortical segmentation', 'subcortical segmentation', 'run recon-all', 'freesurfer T1', 'process brain MRI with freesurfer', 'aseg aparc', or any request to run FreeSurfer on NIfTI MRI data for research analysis.","license":"MIT License (NeuroClaw custom skill – freely modifiable within the project)"}}]