Try to minimize friction at work. 🤨

If you run jobs on an HPC cluster, you know the dance: ssh in, squeue, squint at the columns, tail a log, sacct the exit code, vim the batch script, sbatch again, rsync the results back, repeat. Every step is a context switch, and half of them happen in a separate terminal tab you forgot you left open.

I packaged that whole loop into a Claude Code skill. It’s called slurm, it’s on GitHub, and this post is the tour.

What it is

slurm is a Claude Code plugin that drives SLURM on a remote cluster over SSH, from your laptop. You stay in the same Claude Code session you’re already coding in; the skill does the ssh/sbatch/squeue/sacct/rsync choreography for you and reports back in plain language.

It is not a wrapper that hides SLURM from you. It runs the same commands you’d run by hand — you can read every one — it just removes the tab-switching, the path-juggling, and the “what was that exit code again?” lookups.

What you get

One command, /slurm, with subcommands:

Command	What it does
init	Interactively create ./.slurm/config.yaml (run this first, once per project)
status	Active and recently-finished jobs on a cluster — the default with no subcommand
submit	Fill the sub.slurm template, rsync inputs up, sbatch, and log the job
logs	Tail a job’s stdout/stderr
watch	Live queue state plus log tails for one job
diagnose	Exit code, error log, and common-failure guidance for a dead job
fix	Repair a broken job script (shows you the diff) and resubmit
cancel	scancel a job — after you confirm
sync	rsync local code to the cluster (dry-run first)
log	Manually record a job you submitted outside Claude Code
cron	Set up the background monitor that syncs results and notifies you

Install

Two lines inside Claude Code:

/plugin marketplace add JohnFengg/slurm-marketplace

/plugin install slurm@hpc-tools

The first line adds the marketplace (the JohnFengg/slurm-marketplace GitHub shorthand works; so does a local path while you’re hacking on it). The second installs the slurm plugin from the hpc-tools marketplace.

Quick start

/slurm init      # interactively create ./.slurm/config.yaml for this project

/slurm           # check job status on the default cluster

How it works under the hood

Three pieces, and they’re all readable plain files — nothing hidden:

1. Per-project config — ./.slurm/config.yaml. Cluster identities, the standard sub.slurm template (with <jobname> / <preset> placeholders), and any project-specific submission rules. The skill loads this on every invocation, so the same /slurm submit means the right thing in each repo. No secrets go in here — SSH keys stay in ~/.ssh/config, where they belong.

2. A job ledger — ~/.claude/slurm/state/jobs.csv. Every submission is appended here, pipe-separated:

cluster|jobid|remote_workdir|local_workdir|job_name|submitted_at|status|notified_at

This is the shared memory between the interactive skill and the background monitor. It’s also just a CSV — open it, grep it, delete a row, whatever.

3. An optional background monitor. More on that next, because it’s the best part.

The cron monitor

/slurm cron wires up a small shell script (slurm-monitor.sh) to run on a cron schedule — say, every 10 minutes. On each pass it reads jobs.csv, checks every pending job, and acts on the final state:

• Completed → rsync the result files back to the mirrored local directory and notify “Done.” You decide which files come back via a RESULT_INCLUDES glob list in ~/.claude/slurm/monitor.conf (e.g. OUTCAR CONTCAR vasprun.xml for VASP); leave it unset and it mirrors the whole job dir minus the usual junk.
• Failed / Timeout / OOM / Cancelled → notify with an error summary and append the details to alerts-<cluster>.md so nothing gets lost.
• Node faults. SLURM will happily report State=COMPLETED even when a step was actually killed by a hardware fault (a Bus error, a flaky DIMM, a SIGTERM from the node). The monitor checks DerivedExitCode, and if it’s non-zero it flags the job as NODE_FAULT, names the offending node(s) from sacct, and refuses to sync the broken results over your good ones. That single check has saved me from “why are my numbers garbage?” more than once.

Diagnosing failures

/slurm diagnose <jobid> pulls the exit info, the tail of the error log, and matches against the failure patterns I keep re-learning the hard way:

Symptom	Likely cause	Fix
Exit 137	OOM	Smaller batch, or request more memory
TIMEOUT	Wall time exceeded	Bump --time
Exit 1	Python/script error	Read the traceback, fix, resubmit
Module error	Wrong module load	Check the module names
COMPLETED but DerivedExitCode ≠ 0:0	Silent node fault	Resubmit with --exclude=<bad node>

Then /slurm fix <jobid> proposes the repair, shows you a diff before touching anything remote, and resubmits once you approve.

Requirements (per machine)

It’s deliberately thin on setup:

1. Passwordless SSH to each cluster, configured as a Host alias in ~/.ssh/config. The skill uses your SSH config; it does not manage it. (If you hit Permission denied (publickey), it deliberately won’t try to “fix” your keys — it tells you to sort it out, because guessing at someone’s SSH setup is how bad days start.)
2. A per-project ./.slurm/config.yaml — created by /slurm init.
3. (Optional, only for the cron monitor) ~/.claude/slurm/monitor.conf for your RESULT_INCLUDES globs and DEFAULT_CLUSTER.

A note for non-macOS folks: desktop notifications use macOS osascript. On other platforms they degrade silently — everything else still works, you just don’t get the popup.

Bottom lines

• slurm lets you submit, watch, diagnose, fix, and repair cluster jobs by talking, from inside Claude Code.
• /slurm init probes the cluster so your config reflects reality, not your memory.
• The cron monitor closes the loop: results come home and you get pinged — including for the silent node faults SLURM lies about.

Two lines to install, one init to set up, and you can stop babysitting squeue. Grab it here 👉 github.com/JohnFengg/slurm-marketplace, and tell me what breaks.