Hi everyone,
I just released a small project called fmriprep-skills: two agent skills ($fmri-process, $fmri-followup) that help beginners who are processing a BIDS dataset for the first time avoid common mistakes and get a successful run with fewer retries.
I made it because a lot of fMRIPrep failures are not really about fMRIPrep itself.
- A local run can produce a few hundred GB of derivatives and work files, which can fill the disk quickly.
- Someone may put the output on an external drive, only to find out later that it is exFAT and FreeSurfer cannot create symlinks there.
- Running too many subjects in parallel can make a workstation unresponsive.
- On an HPC, a Slurm array can also hit a FreeSurfer initialization race when several subjects start at the same time.
The skills try to catch these things before the long job starts. With $fmri-process, the agent can:
- audit the dataset, estimate storage needs, check images and TemplateFlow, and report blockers and warnings;
- prepare the runtime if needed by downloading images and templates;
- submit fMRIPrep or XCP-D after confirmation.
Then $fmri-followup can check progress, read subject logs, and look for crash* files under the logs directory to understand the status of each subject.
Each dataset also gets a harness trace file. That way, if you open a new agent window or the context gets compressed, the next agent can read the trace and continue from the previous state instead of guessing what happened. Overall, these two skills can be viewed as a lightweight agent harness.
The easiest way to use the skills is just to talk with your agent:
$fmri-process (or /fmri-process ) help me process /path/to/bids_dataset
$fmri-process ssh to remote and process sub-00[1-5] in /path/to/bids_dataset
Inspection:
$fmri-followup check progress
I would be happy if people tried it and told me what breaks or what feels confusing: