dingyanglyu/matclaw

Describe a materials problem in plain language. MatClaw writes the code, runs the simulation, and delivers results.

         

         

---

Contents

• What is MatClaw?
• Chat Commands
• Built-in Computation Skills
• General Research Tools
• Basic Usage
• Examples
• Computation Stack
• Quick Start
• Architecture
• Configuration
• Documentation
• Contributing
• Citation

What is MatClaw?

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
• 240 built-in skills — 47 skill groups covering computational materials science (electronic structure, phonons, mechanical properties, defects, optics, magnetism, catalysis, batteries, phase diagrams, Monte Carlo, molecular dynamics, and more) plus general research tools (literature search, plotting, document creation, data analysis). 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:3210 with live agent activity, parsed transcripts, and container logs
• Extensible — Conda/pip available inside container; agent can install additional packages on-the-fly

Chat Commands

Control the agent directly from any messaging channel — no terminal or dashboard required.

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.

Built-in Computation Skills

MatClaw ships with 240 SKILL.md files across 47 skill groups, covering the full spectrum of computational materials science plus general research tools. 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.

47 groups / 195 sub-skills / 240 SKILL.md files

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, cheminformatics, 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.

General Research Tools

Beyond materials computation, MatClaw includes 16 general-purpose research skills for literature search, visualization, document creation, and data analysis — grouped under general-tools.

All general tools run locally with no external API keys required.

Basic Usage

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": "[email protected]",
  "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:latest

The agent will autonomously:

1. Parse your request and plan the computation
2. Write input files and scripts
3. Run the simulation (DFT, MD, MC, or MLIP)
4. Analyze results, generate plots, and report back
5. Retry with adjustments if errors occur

Results — including figures, data files, and structured summaries — are returned directly.

Examples

Benchmark tasks adapted from QUASAR. All executed autonomously — the agent writes scripts, runs simulations, and reports results. See examples/ for full details.

Basic Tasks

Cu K-point Convergence (DFT / Quantum ESPRESSO)

Converge bulk Cu energy to < 1 meV/atom. Agent runs 8 QE calculations and plots the convergence curve.

---

Water Density (MD / LAMMPS)

Calculate the density of water at 298 K, 1 bar. Agent builds a SPC/E water box, runs NPT, and reports with diagnostic plots.

---

IRMOF-1 Void Fraction (MC / RASPA3)

Compute helium-accessible void fraction for IRMOF-1 at 298 K. Agent configures RASPA3 Widom insertion MC.

---

Workflow Orchestration

NiO Band Gap (DFT+U / Quantum ESPRESSO)

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.

---

CO₂ Adsorption in UiO-66 (MC / RASPA3)

Calculate CO₂ adsorption isotherm at 4 pressure points. Agent runs GCMC simulations and generates the isotherm plot.

---

Al Melting Point (MD / LAMMPS)

Determine the melting point of aluminum via two-phase coexistence. Agent builds an 8000-atom system and analyzes with bond-order parameters.

---

NaCl Solution Density (MD / LAMMPS + packmol)

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.

---

Results Summary

Computation Stack

Quick Start

One-command setup (recommended)

git clone https://github.com/DingyangLyu/MatClaw.git
cd MatClaw
npm install && npm run setup

The interactive wizard guides you through environment check, container setup, API configuration, smoke test, and channel selection — step by step.

Prerequisites

• Linux (Ubuntu 24.04+ recommended) or macOS
• Docker
• An Anthropic-compatible API key (Claude, DeepSeek, or 44 other providers)

Manual setup

1. Get the container

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:latest

For GPU support:

docker pull ghcr.io/dingyanglyu/matclaw-agent:cuda
docker tag ghcr.io/dingyanglyu/matclaw-agent:cuda matclaw-agent:cuda

Option 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.

2. Run a computation

echo '{
  "prompt": "Calculate the energy of bulk silicon using MACE-MP-0",
  "groupFolder": "test",
  "chatJid": "[email protected]",
  "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:latest

3. Full agent setup with messaging channels

npm install
npm run dev

Configure 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-whatsapp skill, QR code authentication.
• Telegram — Add via /add-telegram skill, Bot API.
• Discord / Slack — Add via /add-discord or /add-slack skill.

Channels are added via the skill system — run the corresponding /add-* command inside claude CLI.

Architecture

┌──────────────────────────────────────────────────────┐
│  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:

1. User sends a natural language prompt (via stdin JSON or messaging channel)
2. Host orchestrator routes it to a fresh Docker container
3. 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
4. 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.

Contributing

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///SKILL.md

See CONTRIBUTING.md for the full guide, including the SKILL.md template, testing instructions, and PR workflow.

Acknowledgments

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
• claude-scientific-skills by K-Dense AI — General research tools (RDKit, DeepChem, arXiv, matplotlib, scientific writing, and more)

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

Documentation

Roadmap

• [x] GPU support (CUDA 12.8 container for PyTorch/MACE — ./container/build.sh --cuda)
• [x] More MLIP models (CHGNet, SevenNet, MatGL pre-installed)
• [x] Materials Project integration (set MP_API_KEY in .env — query structures, phase diagrams, properties)
• [ ] Workflow automation (multi-step calculation pipelines)
• [ ] Jupyter notebook generation for reproducibility

Citation

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  = {[email protected], [email protected], [email protected]},
  year   = {2026},
  url    = {https://github.com/DingyangLyu/MatClaw}
}

License

Apache License 2.0