molagent
v1.0.0 · pi coding agent package

molagent

OPLS-AA / LAMMPS / Gaussian skills for the pi coding agent — packaged with the discipline that keeps molecular-simulation agents safe on shared HPC.

12 skills RULE #0 login-node guard SLURM-aware runner Critic + Verifier subagents
pi install git:git@github.com:your-org/pi-molagent
Get started Documentation

The gap it closes

Coding agents don't know how shared HPC works

General-purpose coding agents will gladly run NumPy on a login node, invent SLURM directives, and overwrite working force-field files. molagent replaces those failure modes with executable rules, battle-tested skills, and a config that travels between clusters.

Without molagent

  • Agent runs python -c "import numpy" on the login node and admins file a ticket.
  • SLURM scripts have invented partitions, missing --account, hour-units off-by-60.
  • LigParGen paths, BOSS bind-mounts, and Gaussian scratch dirs are baked into every skill.
  • "Critic" and "verifier" exist only as good intentions in a prompt.
  • Knowledge — how Puma differs from Ocelote, how fix shake bites — lives in screenshots in Slack.

With molagent

  • A tool_call hook intercepts heavy-compute Python on the login node; configurable strict/warn/off.
  • One molagent.json declares accounts, partitions, walltimes, modules; skills read it through a stdlib-only helper.
  • 12 skills wrap the OPLS-AA pipeline end-to-end; binaries and containers are config keys, not hard-coded paths.
  • /critic and /verify commands inject role-protocols stored in agents/*.md.
  • Cluster reference, LAMMPS gotchas, and incident lessons are first-class steering — loaded on demand via slash commands.

Highlights

What it ships

A pi package that registers an extension, twelve skills, eight prompt templates, and a steering library — all driven from a single config file.

FF

Full OPLS-AA pipeline

From mol2 → LigParGen / BOSS parameterisation → LAMMPS data files → DFT-refined charges → dihedral re-fits.

⚑

RULE #0 login-node guard

A tool_call hook intercepts numpy / scipy / rdkit / torch on login nodes. strict blocks, warn confirms, off disables.

cfg

One config, many clusters

Binaries, SLURM accounts, partition fallbacks, LAMMPS defaults, scratch dirs — all in molagent.json. /molagent:init auto-discovers what it can.

srv

SLURM / local / dry-run

A stdlib-only Python helper renders {{ placeholder }} SLURM templates and dispatches to sbatch, mpirun, or prints them for review.

⚖

Critic + Verifier protocols

Markdown role definitions under agents/ turn into /critic and /verify slash commands. Devil's-advocate review and blind re-derivation, on demand.

📚

Steering as a library

Rule set, cluster reference, LAMMPS / Gaussian / plot-discipline notes, and an incident-log archive — loaded on demand with /hpc, /lammps, /gaussian, /incident-log.

How it fits together

From install to first SLURM job

Four steps, each ~30 seconds. The first three configure the agent; the fourth is the agent doing the work.

1

Install

Pi reads package.json, registers the extension, and auto-discovers skills/ and prompts/.

pi install git:git@github.com:your-org/pi-molagent
# or project-local:
pi install -l ./pi-molagent
2

Activate steering

Pi looks for AGENTS.md in cwd-and-ancestors and in ~/.pi/agent/. Point it at the bundled rule set:

ln -s /abs/path/to/pi-molagent/steering/AGENTS.md \
      ~/.pi/agent/AGENTS.md
3

Generate a config

Inside pi, /molagent:init writes a starter .pi/molagent.json with auto-detected binary paths and a sensible ntasks.

/molagent:init       # write .pi/molagent.json
/molagent:doctor     # see what's ready / blocked
4

Run a skill

Skills read the merged config from $MOLAGENT_EFFECTIVE_CONFIG. The runner renders SLURM templates and dispatches according to runner.mode.

"Parameterise this monomer with OPLS-AA and submit
 a 2 ns NVE on Puma high_priority."

12 skills

The bundled toolkit

Each skill is a SKILL.md + script directory. Pi auto-discovers them; the agent invokes one when the task description matches.

structure-analyze Mol2 / PDB analysis, ring detection, OPLS atom typing
polymer-builder Oligomers and chains from a monomer mol2
ligpargen-from-mol OPLS-AA parameterisation via LigParGen + BOSS
opls-pipeline End-to-end OPLS-AA: param → data → validate
solvent-pack Packmol solvent boxes with LAMMPS equilibration
merge-data Merge multiple LAMMPS data files into one system
wrap-unwrap Wrap / unwrap LAMMPS trajectories across PBC
extract-molecules Extract and renumber molecules from bulk data
dft-charges DFT charges (Gaussian g16, Hirshfeld / RESP)
dihedral-fit-pipeline DFT scan → LAMMPS dihedral coefficients
plot-standards Publication-quality matplotlib defaults
find-skills List and describe available molagent skills