Describe a materials problem in plain language. MatClaw writes the code, runs the simulation, and delivers results.
- What is MatClaw?
- Chat Commands
- Built-in Computation Skills
- Basic Usage
- Examples
- Computation Stack
- Quick Start
- Architecture
- Configuration
- Documentation
- Contributing
- Citation
MatClaw is an AI agent that autonomously performs materials science computations. You describe a task in natural language — it writes Python/shell scripts, runs them inside an isolated Docker container equipped with a full computation stack, and returns the results.
Send a task via Feishu (or any channel). Get back scripts, simulations, plots, and analysis — no manual coding required.
Key Features:
- Autonomous computation — Understands your task, writes code, executes it, analyzes output, retries on errors
- 221 built-in computation skills — 44 skill groups covering the full spectrum of computational materials science: electronic structure, phonons, mechanical properties, defects, optical/magnetic/topological properties, catalysis, batteries, phase diagrams, transport, spectroscopy, Monte Carlo, molecular dynamics, and more. Each skill contains complete runnable scripts, parameter guides, and method selection decision trees. See Materials Compute Skills Reference for the full inventory.
- VASP support — Connect your own VASP installation via SSH (HPC cluster) or local mount. The agent generates inputs, submits jobs, and parses results automatically. See VASP Integration.
- GPU acceleration — Optional CUDA-enabled container (
./container/build.sh --cuda) for GPU-accelerated MACE, CHGNet, SevenNet, and MatGL. Auto-detects GPU at runtime with graceful CPU fallback. - Multiple MLIP models — MACE-MP-0 (pre-installed), CHGNet, SevenNet, MatGL — all pre-installed and ready for rapid screening and molecular dynamics
- All-in-one container — QE 7.5, LAMMPS, RASPA3, MACE, pymatgen, ASE, PyTorch pre-installed and ready
- Secure isolation — Every computation runs in a disposable Docker container with filesystem isolation
- Flexible LLM backend — Works with Anthropic Claude, DeepSeek, or any Anthropic-compatible API
- Multi-channel access — Chat via Feishu, DingTalk, Gmail, WhatsApp, Telegram, Discord, Slack
- Chat commands —
/watch,/status,/stop,/sessions,/new,/resume,/compact— manage sessions, monitor progress, and control the agent directly from chat - Real-time dashboard — Web UI at
localhost:3210with live agent activity, parsed transcripts, and container logs - Extensible — Conda/pip available inside container; agent can install additional packages on-the-fly
Control the agent directly from any messaging channel — no terminal or dashboard required.
| Command | Description |
|---|---|
/watch |
See what the agent is doing right now (recent tool calls, reads, bash commands) |
/status |
Agent status — running/idle, current session, container name, queued tasks |
/stop |
Force stop a running agent |
/sessions |
List all conversation sessions (ID, timestamp, size, active marker) |
/new |
Start a fresh conversation with no prior memory |
/resume [id] |
Restore previous session, or switch to any session by ID prefix |
/compact [focus] |
Compress agent memory. Optionally specify what to keep (e.g. /compact keep only VASP config) |
/help |
Show all available commands |
Session management — Every conversation is a resumable session. Use /new to start clean, /sessions to browse history, and /resume to jump back to any previous context. The agent picks up exactly where it left off.
Real-time monitoring — Send /watch at any time to see the agent's recent activity without waiting for it to finish. For a full graphical view, open the built-in dashboard at http://localhost:3210.
MatClaw ships with 221 SKILL.md files across 44 skill groups, covering the full spectrum of computational materials science. Each skill contains complete runnable scripts, parameter guides, method selection decision trees, and troubleshooting tables — enabling the agent to autonomously execute any mainstream materials computation workflow.
44 groups / 177 sub-skills / 221 SKILL.md files
| # | Skill Group | Sub-Skills | Contents |
|---|---|---|---|
| 1 | 2d-materials | 4 | band-edges, layer-manipulation, stacking-energy, vacuum-resize |
| 2 | advanced-electronic | 5 | gw-approximation, hubbard-u, spin-orbit-coupling, topological-invariants, van-der-waals |
| 3 | agent-browser | 0 | (browser automation, non-computation) |
| 4 | alloy-disorder | 2 | cluster-expansion, sqs-generation |
| 5 | band-advanced | 3 | 3d-band-structure, band-unfolding, hybrid-dft-bands |
| 6 | battery-electrode | 2 | intercalation-voltage, ion-diffusion |
| 7 | biomolecular-md | 1 | openmm-simulation |
| 8 | bonding-analysis | 10 | bader2pqr, bader-charge, charge-density, charge-density-difference, charge-format-conversion, elf-analysis, lobster-cohp, orbital-projection, planar-charge, stm-simulation |
| 9 | catalysis-electrochem | 6 | band-center, imaginary-freq-correction, implicit-solvation, neb-analysis, reaction-kinetics, thermal-corrections |
| 10 | catalyst-screening | 3 | d-band-center, overpotential, scaling-relations |
| 11 | code-interfaces | 5 | boltztrap-interface, ifc-analysis, phonopy-interface, vasp-qe-converter, wannier90-interface |
| 12 | defects-reactions | 13 | activation-relaxation-technique, adsorption-energy, configuration-coordinate, defect-thermodynamics, interstitial-defect, migration-barrier, neb-transition-state, point-defect, reaction-pathway, substitution-defect, surface-adsorption, surface-energy, vacancy-formation |
| 13 | dft-corrections | 3 | hubbard-u, spin-orbit-coupling, vdw-correction |
| 14 | electronic-structure | 8 | band-structure, convergence-testing, density-of-states, inverse-participation-ratio, projected-dos, scf-relax, spatially-resolved-dos, vasp-bands |
| 15 | electron-phonon | 4 | deformation-potential, electronic-transport, elph-coupling, superconductivity |
| 16 | fermi-surface | 3 | 2d-fermi-surface, 3d-fermi-surface, projected-fermi-surface |
| 17 | ferroelectric | 5 | born-effective-charge, dielectric-tensor, ferroelectric-switching, piezoelectric, polarization |
| 18 | high-throughput | 8 | batch-calculations, batch-screening, convergence-automation, materials-filtering, matpes-dual-static, phase-stability, property-prediction, screening-workflow |
| 19 | interface | 2 | grain-boundary, heterostructure |
| 20 | kpath-utilities | 5 | 1d-kpath, 2d-kpath, bulk-kpath, cp2k-kpath, phonopy-kpath |
| 21 | magnetic-properties | 3 | magnetic-anisotropy, magnetic-ordering, spin-polarized |
| 22 | materials-compute | 0 | (root skill: QE/LAMMPS/MACE environment reference) |
| 23 | materials-databases | 2 | 2d-semiconductors, materials-project |
| 24 | mechanical-properties | 5 | angular-mechanics, elastic-constants, energy-strain-method, equation-of-state, stress-strain-method |
| 25 | mlip-guide | 4 | mace-advanced, mlip-validation, torchsim-batch, universal-mlip |
| 26 | molecular-qchem | 1 | gaussian-qchem-workflow |
| 27 | monte-carlo | 5 | adsorption-isotherm, gas-adsorption, gas-separation, gcmc-simulation, pore-analysis |
| 28 | optical-properties | 6 | absorption-spectrum, dielectric-function, joint-dos, optical-conductivity, slme, transition-dipole |
| 29 | phase-diagram | 2 | convex-hull, pourbaix-diagram |
| 30 | phase-transition | 6 | amorphous-structure, melting-point-coexistence, metadynamics, mpmorph-melting, order-parameter, phase-diagram |
| 31 | piezoelectric | 1 | piezoelectric-tensor |
| 32 | potential-analysis | 3 | macroscopic-average, planar-average, work-function |
| 33 | semiconductor-kit | 4 | angular-effective-mass, band-gap, effective-mass, fermi-velocity |
| 34 | spectroscopy | 2 | raman-ir, xas-xanes |
| 35 | spin-texture | 2 | 2d-spin-texture, 3d-spin-texture |
| 36 | structure-models | 8 | alloy-builder, defect-builder, heterostructure, moire-superlattice, nanowire-nanotube, quantum-dot, supercell-builder, surface-builder |
| 37 | structure-tools | 8 | advanced-optimization, format-conversion, input-generation, pdf-analysis, structure-editing, structure-matching, symmetry-analysis, xrd-pattern |
| 38 | surface-energy | 2 | surface-energy-calc, wulff-construction |
| 39 | thermal-properties | 13 | anharmonicity, bond-distribution, free-energy-calculation, gruneisen-qha, md-trajectory-tools, molecular-dynamics, msd-diffusion, phonon, phonon-from-outcar, quasi-harmonic-debye, rdf-analysis, thermal-conductivity, vacf-vdos |
| 40 | thermoconductivity | 1 | lattice-thermal-conductivity |
| 41 | topological | 2 | berry-curvature, z2-invariant |
| 42 | transport-properties | 2 | boltzmann-transport, kpoints-transport |
| 43 | wannier-functions | 1 | wannier90-workflow |
| 44 | wavefunction-analysis | 2 | real-space-wavefunction, wavefunction-parity |
Coverage: electronic structure, mechanics, thermodynamics, phonons, defects, optics, magnetism, topology, catalysis, batteries, phase diagrams, ferroelectric/piezoelectric, transport, surfaces, interfaces, 2D materials, alloys, Monte Carlo, molecular dynamics, machine learning potentials, biomolecular simulation, quantum chemistry, and more. Verified against atomate2, aiida-quantumespresso, and aiida-vasp — all workflow capabilities are covered. See Materials Compute Skills Reference for detailed descriptions of each skill.
Send a natural language task via any connected channel (Feishu, WhatsApp, Gmail, etc.) or directly via Docker:
echo '{
"prompt": "Calculate the band gap of silicon using DFT (Quantum ESPRESSO)",
"groupFolder": "test",
"chatJid": "test@g.us",
"isMain": false,
"secrets": {
"ANTHROPIC_API_KEY": "your-api-key",
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
}
}' | docker run -i -v ./workspace:/workspace/group matclaw-agent:latestThe agent will autonomously:
- Parse your request and plan the computation
- Write input files and scripts
- Run the simulation (DFT, MD, MC, or MLIP)
- Analyze results, generate plots, and report back
- Retry with adjustments if errors occur
Results — including figures, data files, and structured summaries — are returned directly.
Benchmark tasks adapted from QUASAR. All executed autonomously — the agent writes scripts, runs simulations, and reports results. See examples/ for full details.
Converge bulk Cu energy to < 1 meV/atom. Agent runs 8 QE calculations and plots the convergence curve.
Calculate the density of water at 298 K, 1 bar. Agent builds a SPC/E water box, runs NPT, and reports with diagnostic plots.
Compute helium-accessible void fraction for IRMOF-1 at 298 K. Agent configures RASPA3 Widom insertion MC.
Calculate the electronic band gap of NiO. Agent recognizes a strongly correlated system and autonomously applies DFT+U.
Tip
The agent was only asked to "calculate the band gap of NiO" — it independently decided DFT+U was necessary for a correlated oxide, chose appropriate U values, and ran the full SCF → NSCF → DOS workflow.
Calculate CO₂ adsorption isotherm at 4 pressure points. Agent runs GCMC simulations and generates the isotherm plot.
Determine the melting point of aluminum via two-phase coexistence. Agent builds an 8000-atom system and analyzes with bond-order parameters.
Calculate density of 1 mol/L NaCl solution. Agent autonomously installs packmol (not pre-installed), builds the system, and runs MD.
Tip
packmol was not pre-installed in the container. The agent detected the missing dependency, downloaded and compiled it from source (retrying 3 times with different approaches), then proceeded with the simulation.
| Example | Method | Engine | Reference | Agent Result |
|---|---|---|---|---|
| Cu k-point convergence | DFT | QE | < 1 meV/atom | Converged at 12×12×12 |
| Water density | MD | LAMMPS | 0.997 g/cm³ | 0.985 g/cm³ |
| IRMOF-1 void fraction | MC | RASPA3 | 0.7988 | 0.8025 |
| NiO band gap | DFT+U | QE | 4.0 eV | 2.11 eV |
| CO₂ in UiO-66 | MC | RASPA3 | 5.98 mmol/g | 5.48 mmol/g |
| Al melting point | MD | LAMMPS | 933 K | ~850–880 K |
| NaCl solution density | MD | LAMMPS | 1.038 g/cm³ | 1.033 g/cm³ |
| Engine | Version | Method | Use Cases |
|---|---|---|---|
| Quantum ESPRESSO | 7.5 | DFT | Electronic structure, band gaps, DOS, phonons, elastic constants |
| LAMMPS | 2021 | MD | Thermal properties, diffusion, mechanical properties, phase transitions |
| RASPA3 | 3.0.16 | MC | Gas adsorption in MOFs/zeolites, isotherms, Henry constants |
| VASP | 5.x / 6.x | DFT | Full-featured DFT via external connection (setup guide) |
| MACE-MP-0 | latest | MLIP | Universal ML potential, fast energy/force/stress predictions |
Python Materials Science Stack (all pre-installed)
| Package | Purpose |
|---|---|
| pymatgen | Crystal structures, phase diagrams, electronic structure analysis |
| ASE | Atoms objects, calculators, optimization, molecular dynamics |
| MACE-torch | Universal ML interatomic potentials |
| mp-api | Materials Project database access |
| spglib | Space group / symmetry analysis |
| PyTorch | ML framework (CPU) |
| numpy, scipy, matplotlib, pandas, seaborn | Scientific computing & visualization |
- Linux (Ubuntu 24.04+ recommended) or macOS
- Docker
- An Anthropic-compatible API key (Claude, DeepSeek, etc.)
Option A — Pull pre-built image (recommended):
docker pull ghcr.io/dingyangLyu/matclaw-agent:latest
docker tag ghcr.io/dingyangLyu/matclaw-agent:latest matclaw-agent:latestFor GPU support:
docker pull ghcr.io/dingyangLyu/matclaw-agent:cuda
docker tag ghcr.io/dingyangLyu/matclaw-agent:cuda matclaw-agent:cudaOption B — Build from source:
git clone https://github.com/DingyangLyu/MatClaw.git
cd MatClaw
./container/build.sh # CPU
./container/build.sh --cuda # GPU (requires NVIDIA Container Toolkit)Note
Building from source takes ~10 minutes (compiles QE 7.5). Pulling the pre-built image is much faster.
echo '{
"prompt": "Calculate the energy of bulk silicon using MACE-MP-0",
"groupFolder": "test",
"chatJid": "test@g.us",
"isMain": false,
"secrets": {
"ANTHROPIC_API_KEY": "your-api-key",
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
}
}' | docker run -i -v ./workspace:/workspace/group matclaw-agent:latestnpm install
npm run devConfigure at least one messaging channel to chat with your agent:
- Feishu (飞书) — WebSocket connection, no public URL needed. Recommended for China users.
- DingTalk (钉钉) — Stream Mode (WebSocket), no public URL needed. Auto-registers groups on first message.
- Gmail — Send computation tasks via email, receive results back.
- WhatsApp — Add via
/add-whatsappskill, QR code authentication. - Telegram — Add via
/add-telegramskill, Bot API. - Discord / Slack — Add via
/add-discordor/add-slackskill.
Channels are added via the skill system — run the corresponding /add-* command inside claude CLI.
┌──────────────────────────────────────────────────────┐
│ Host (Node.js) │
│ ┌────────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Channels │→│ SQLite │→│ Container Runner │ │
│ │ (WhatsApp, │ │ (msgs, │ │ (spawns Docker │ │
│ │ Telegram, │ │ tasks, │ │ containers) │ │
│ │ Discord…) │ │ state) │ └────────┬─────────┘ │
│ └────────────┘ └──────────┘ │ │
└──────────────────────────────────────────┼───────────┘
│ stdin/stdout JSON
┌──────────────────────────────────────────┼───────────┐
│ Container (Ubuntu 24.04) │ │
│ ┌───────────────────────────────────────┘ │ │
│ │ Agent Runner (Claude Agent SDK) │ │
│ │ ┌─────────────────────────────────────────┐ │ │
│ │ │ LLM ←→ Tool Use (bash, browser, MCP) │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Computation Tools: │ │
│ │ ┌─────────┐ ┌────────┐ ┌───────┐ ┌──────┐ │ │
│ │ │ QE 7.5 │ │ LAMMPS │ │RASPA3 │ │ MLIP │ │ │
│ │ └─────────┘ └────────┘ └───────┘ └──────┘ │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ Python: pymatgen, ASE, torch, numpy, … │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
How it works:
- User sends a natural language prompt (via stdin JSON or messaging channel)
- Host orchestrator routes it to a fresh Docker container
- Inside the container, Claude Agent SDK receives the prompt and iteratively:
- Writes computation scripts (Python, shell, QE input files, LAMMPS scripts…)
- Executes them via bash tool
- Reads and analyzes output
- Retries or adjusts if errors occur
- Final results returned to user via stdout markers
For full architecture details, see docs/SPEC.md. For the security model and container isolation design, see docs/SECURITY.md.
Configuration
MatClaw works with any Anthropic-compatible API. Pass credentials via stdin JSON:
{
"secrets": {
"ANTHROPIC_API_KEY": "your-key",
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
}
}Tested providers:
| Provider | Base URL | Notes |
|---|---|---|
| Anthropic | https://api.anthropic.com |
Claude models, recommended |
| DeepSeek | https://api.deepseek.com/anthropic |
Cost-effective, tool_use support |
| Variable | Default | Description |
|---|---|---|
CONTAINER_RUNTIME |
docker |
Container runtime (docker, podman, nerdctl) |
MAX_CONCURRENT_CONTAINERS |
5 |
Max parallel agent containers |
AGENT_TIMEOUT |
300 |
Agent execution timeout (seconds) |
We welcome contributions — especially new computation skills! Adding a skill is as simple as writing a single SKILL.md file with runnable scripts and parameter guides. No need to touch core code.
container/skills/<group>/<your-skill>/SKILL.md
See CONTRIBUTING.md for the full guide, including the SKILL.md template, testing instructions, and PR workflow.
MatClaw is built on NanoClaw and relies on the following open-source projects:
- Quantum ESPRESSO — DFT calculations
- LAMMPS — Molecular dynamics
- RASPA3 — Monte Carlo simulations
- MACE — Machine learning interatomic potentials
- pymatgen — Python materials analysis
- ASE — Atomic simulation environment
- Claude Agent SDK — AI agent framework
- QUASAR — Benchmark test cases referenced from this project
The built-in computation skills were designed and verified against the following workflow frameworks:
- atomate2 — Materials Project's computational workflows (VASP, QE, force fields, and more)
- pyiron_atomistics — Integrated materials science workflow platform (Murnaghan EOS, QHA, SQS, Debye model, ART, metadynamics, and more)
- VASPKIT — VASP pre-/post-processing toolkit
- AiiDA — Automated Interactive Infrastructure and Database for Computational Science
- aiida-quantumespresso — AiiDA plugin for Quantum ESPRESSO workflows
- aiida-vasp — AiiDA plugin for VASP workflows
Project Structure
matclaw/
├── src/ # Host orchestrator
│ ├── index.ts # Main loop: messages, agents, scheduling
│ ├── container-runner.ts # Spawns isolated Docker containers
│ ├── db.ts # SQLite (messages, tasks, state)
│ ├── channels/ # Messaging channel registry
│ └── ...
├── container/
│ ├── Dockerfile # Multi-stage build (QE builder + runtime)
│ ├── agent-runner/ # Claude Agent SDK runner (inside container)
│ └── skills/ # 221 computation skills (44 groups)
│ ├── materials-compute/ # Root: computation engine docs
│ ├── electronic-structure/ # Band structure, DOS, SCF
│ ├── thermal-properties/ # Phonons, QHA, MD, thermal transport
│ ├── mechanical-properties/ # Elastic constants, EOS
│ ├── defects-reactions/ # Defects, NEB, adsorption, CCD
│ ├── optical-properties/ # Dielectric function, absorption
│ ├── magnetic-properties/ # Spin ordering, MAE
│ ├── topological/ # Z2, Berry curvature
│ ├── catalysis-electrochem/ # Reaction kinetics, d-band
│ ├── battery-electrode/ # Intercalation voltage, ion diffusion
│ ├── monte-carlo/ # GCMC, gas adsorption (RASPA3)
│ ├── ... # 34 more groups
│ └── agent-browser/ # Browser automation
└── groups/ # Per-group isolated memory
| Document | Description |
|---|---|
| Architecture Spec | Full system architecture and design |
| Security Model | Container isolation and trust model |
| Requirements | Original requirements and design decisions |
| Feishu Setup | Feishu channel configuration guide |
| DingTalk Setup | DingTalk channel configuration guide |
| Gmail Setup | Gmail channel configuration guide |
| SDK Deep Dive | Claude Agent SDK internals |
| Materials Compute Skills | Full inventory of 221 built-in computation skills |
| VASP Integration | Connect your VASP installation (SSH or local) |
| Creating Skills | How to create a new skill (template included) |
| Skills Architecture | How the skill system works (internals) |
- GPU support (CUDA 12.8 container for PyTorch/MACE —
./container/build.sh --cuda) - More MLIP models (CHGNet, SevenNet, MatGL pre-installed)
- Materials Project integration (set
MP_API_KEYin.env— query structures, phase diagrams, properties) - Workflow automation (multi-step calculation pipelines)
- Jupyter notebook generation for reproducibility
If you use MatClaw in your research, please cite:
@software{matclaw2026,
title = {MatClaw: AI-Powered Autonomous Materials Science Agent},
author = {Dingyang Lyu and Baole Wei and Hongwei Du and Yongheng Li and Feng Yu},
email = {s-ldy25@bza.edu.cn, weibaole@zgci.ac.cn, duhongwei@zgci.ac.cn},
year = {2026},
url = {https://github.com/DingyangLyu/MatClaw}
}