mdclaw

MDClaw: Your personal MD assistant

From PDB ID to Production-Ready Simulation - Automated

MDClaw transforms any PDB structure, FASTA sequence, or ligand-SMILES into a production-ready Amber/OpenMM simulation setup through AI-powered tools and domain knowledge.

Architecture: CLI tools + Skills (domain knowledge prompts) — works with Claude Code, Cursor, Windsurf, or any AI coding assistant.

---

For Users

Installation (Claude Code Plugin)

Install MDClaw as a Claude Code plugin:

/plugin marketplace add matsunagalab/mdclaw
/plugin install mdclaw@mdclaw

On first session start, the container (~4.6 GB) is automatically downloaded.

Container Runtime Requirements

You need one of the following runtimes on the host:

Runtime	Best for	Install
Singularity / Apptainer	HPC clusters	Singularity / Apptainer
Docker	macOS, Linux desktop	Docker Desktop

bin/mdclaw auto-detects the available runtime (Singularity first, Docker as fallback). You can force one with:

export MDCLAW_RUNTIME=docker      # force Docker
export MDCLAW_RUNTIME=singularity  # force Singularity

GPU Requirements

• NVIDIA driver 530+ (CUDA 12.1 or newer)
• Verified GPUs: RTX 2080 Ti, RTX A6000, A100
• CPU-only mode works without GPU (slower, for testing)

Usage

After installation, four skills (slash commands) become available:

Command	Purpose
/mdclaw:md-prepare	Structure acquisition → cleaning → solvation → topology → quick MD
/mdclaw:md-run	Equilibration (NVT + NPT with CA restraints) + production MD
/mdclaw:md-analyze	Trajectory analysis (RMSD, RMSF, energy, hydrogen bonds)
/mdclaw:hpc-run	SLURM job submission, monitoring, error recovery

Example Conversations

Single system, end-to-end:

> /mdclaw:md-prepare 1AKE chain A, no ligands, explicit water, defaults

> /mdclaw:md-run run 10 ns production MD

Multiple targets (batch):

> /mdclaw:md-prepare 1AKE, 4AKE chain A, explicit water, defaults

> /mdclaw:md-run batch_a1b2c3d4, 100 ns on GPU partition

HPC workflow:

> /mdclaw:hpc-run submit 100 ns MD of 1AKE to GPU partition on node gpu01

> /mdclaw:hpc-run check job 12345

> /loop 15m /mdclaw:hpc-run check job 12345 and report when done

Direct CLI Usage

You can also invoke mdclaw directly (outside Claude Code):

# List all tools
mdclaw --list

# Download a structure
mdclaw download_structure --pdb-id 1AKE --format pdb --output-dir job_1AKE

# Run a quick MD
mdclaw run_production \
  --prmtop-file job_1AKE/topology/system.parm7 \
  --inpcrd-file job_1AKE/topology/system.rst7 \
  --simulation-time-ns 0.1 \
  --output-dir job_1AKE

bin/mdclaw is auto-added to your PATH by the plugin installer.

Default MD Parameters

MDClaw uses the following defaults, aligned with OpenMM best practices:

Parameter	Default	Notes
Force field	ff19SB	Paired with OPC water
Water model	OPC	4-point, best accuracy
Buffer distance	15 Å	Prevents periodic image interactions
Salt	0.15 M NaCl	Physiological
Temperature	300 K
Pressure	1 bar (NPT)
Integrator	LangevinMiddleIntegrator	Friction 1/ps
Timestep	4 fs	With HMR (hydrogenMass=4 amu)
Constraints	HBonds
Nonbonded method	PME (explicit) / NoCutoff (implicit)
Equilibration	NVT (10k steps, 1fs) + NPT (10k steps, 2fs)	CA positional restraints (100 kJ/mol/nm²)

HPC / SLURM Usage

MDClaw provides SLURM tools for batch job submission, monitoring, and error recovery:

# Discover cluster partitions, GPUs, nodes
mdclaw inspect_cluster

# Submit a production MD job
mdclaw submit_job \
  --script "mdclaw run_production --prmtop-file /abs/path/sys.parm7 ..." \
  --partition gpu --nodelist gpu01 --gpus 1 \
  --time-limit "24:00:00" --memory "64G"

# Chain equilibration → production via dependency
EQ_JOB=$(mdclaw submit_job --script "mdclaw run_equilibration ..." --gpus 1 ...)
mdclaw submit_job --script "mdclaw run_production ..." \
  --dependency "afterok:${EQ_JOB}" --gpus 1 ...

# Check job status (updates local JSONL tracker)
mdclaw check_job --job-id 12345

# List all tracked jobs (full history)
mdclaw list_tracked_jobs --sync

Resource Policy

Set resource limits on shared clusters to prevent overuse:

mdclaw set_policy \
  --allowed-partitions gpu cpu-small \
  --max-gpus-per-job 2 \
  --max-time-limit "24:00:00" \
  --max-memory "128G" \
  --default-account myproject

mdclaw show_policy

Policy is stored in .mdclaw_cluster.json. submit_job rejects requests exceeding the limits.

Reproducibility

Each job directory contains progress.json with: