mdclaw

MDClaw

MDClaw provides skills and CLIs for vibe-MD (Molecular Dynamics) simulations and autonomous scientific investigation in the Amber/OpenMM ecosystem. It helps an AI agent turn scientific intent into reproducible atomistic work: prepare systems, run equilibration and production MD, analyze trajectories, branch hypotheses, and package evidence with provenance.

What MDClaw Can Do

• Turn a scientific question into a study plan with observables and decision criteria, then run the planned MD jobs end-to-end.
• Prepare MD systems from PDB IDs, AlphaFold/UniProt entries, or local structure files.
• Generate monomer conformational source ensembles from MD surrogate models such as BioEmu, then hand selected candidates to the standard MD workflow.
• Start from a study-level scientific question, translate it into a small MD plan, then organize one or more job DAGs under that study.
• Inspect chains, ligands, waters, ions, glycans, DNA/RNA, and modified residues before committing to a setup.
• Clean structures, preserve selected ligands when safe, solvate systems, and assign Amber/OpenMM force fields.
• Build OpenMM-ready topology artifacts, then run equilibration and production MD with restartable state files.
• Branch workflows for mutations, PTMs, ligand choices, solvent models, temperatures, seeds, and protocols.
• Run locally, through containers, or on SLURM/HPC systems.
• Analyze trajectories and package reproducible evidence, provenance, figures, and Methods-style reports.
• Evaluate MD agents with the included MDPrepBench / MDStudyBench datasets and scorer.

MDClaw is split into two things that are deployed together but should be understood separately:

Layer	What It Is	Main Files
Skill layer	Agent-facing MD decision policy and procedures	skills/, .agents/skills/, .claude/skills/
MD runtime	The scientific software stack and CLI that perform the work	bin/mdclaw, mdclaw/, container/, hooks/

The skills are text and are portable across agent harnesses. The MD runtime is the packaged scientific stack behind the CLI: a conda environment, Singularity/Apptainer SIF, Docker image, or local editable install.

Install / Deploy

Choose the path that matches your agent. After installation, run scripts/mdclaw-doctor.sh when using a repo checkout; it checks the runtime, OpenMM, AmberTools, container availability, and skill discovery.

Claude Code Plugin

Use this when you want /mdclaw:* slash commands and plugin-managed runtime setup.

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

The plugin provides:

• .claude-plugin/: marketplace metadata.
• hooks/hooks.json: SessionStart hook that prepares the packaged MD runtime.
• bin/mdclaw: runtime wrapper that chooses conda, SIF, or Docker.
• skills/: the same MDClaw skills used by other agents.

The plugin prepares the container runtime on first session start. On HPC it prefers a SIF for Singularity/Apptainer; on desktop it can use Docker. This is only the execution environment for mdclaw <tool>; skill discovery remains the same text files under skills/.

Pi

Pi reads skills from the repository package metadata:

pi install git:github.com/matsunagalab/mdclaw@main

package.json points Pi at ./skills. You still need one MD runtime: the mdclaw conda env, a SIF through MDCLAW_SIF, Docker through MDCLAW_DOCKER_IMAGE, or the plugin/container wrapper.

Claude Code, Codex, OpenCode, and Generic Agents

Use this path when an agent discovers skills from repo-local skill mirrors.

git clone https://github.com/matsunagalab/mdclaw
cd mdclaw
scripts/install-agent-skills.sh
scripts/mdclaw-doctor.sh

scripts/install-agent-skills.sh creates .agents/skills/<name> and .claude/skills/<name> symlinks to skills/<name>. Use scripts/install-agent-skills.sh --copy if your agent or filesystem does not follow symlinks.

Repo-local Claude Code uses .claude/skills/ for skill discovery. The older repo-local short commands such as /md-prepare are intentionally not tracked; use the discovered skills directly, or install the Claude plugin when you want the plugin command namespace such as /mdclaw:md-prepare.

Local Runtime

For development or non-plugin usage, create the conda environment:

conda env create -f environment.yml
conda activate mdclaw
pip install -e .
mdclaw --list

bin/mdclaw chooses a runtime in this order:

1. MDCLAW_RUNTIME=conda|singularity|apptainer|docker, if set.
2. A conda env named mdclaw, if available.
3. Singularity/Apptainer with MDCLAW_SIF or an auto-downloaded SIF.
4. Docker image ghcr.io/matsunagalab/mdclaw:<version-or-latest>.
5. A local mdclaw on PATH.