dingyanglyu/matclaw

1. This repo is split into two major execution domains: a host orchestrator in src/ and a sandboxed computation container in container/. The host accepts tasks, persists state, routes messages, and launches containers; the container runs the actual AI agent and scientific tools.

2. The primary runtime entrypoint is src/index.ts, which coordinates inbound prompts, session/task handling, scheduling, and result delivery. It relies on src/db.ts for persistence and src/router.ts / src/task-scheduler.ts for dispatching work across sessions and containers.

3. Messaging is handled by a channel subsystem in src/channels/. The repo supports multiple ingress/egress paths such as Feishu, DingTalk, Gmail, Telegram, WhatsApp, Discord, Slack, and a web channel. Each channel adapter normalizes external messages into the same internal task model.

4. The host’s most important boundary is the container runner in src/container-runner.ts and src/container-runtime.ts. These modules spawn disposable Docker containers, pass prompt/state via stdin/stdout JSON, enforce runtime limits, and isolate filesystem access. The README’s diagram reflects this as the handoff point between host and container.

5. Inside the container, container/agent-runner/ is the autonomous executor. It is built around the Claude Agent SDK and an engine abstraction under container/agent-runner/src/engines/, with implementations for Claude and Codex. This layer turns a prompt into iterative tool use: write files, run shell commands, inspect outputs, and retry.

6. The scientific compute stack lives entirely inside the container image. The repo packages Quantum ESPRESSO, LAMMPS, RASPA3, MACE/MLIP tooling, Python scientific libraries, and optional CUDA support. This is the core “workhorse” subsystem that makes the repo a materials-science agent rather than a generic chatbot.

7. Skills are the main knowledge/workflow layer. The .claude/skills/ tree contains many packaged skill definitions and modification templates, while skills-engine/ provides the repository’s internal machinery for applying, merging, rebasing, migrating, and uninstalling skills. Conceptually, skills are a large library of reusable domain workflows that the agent can invoke or that can be installed/updated across the repo.

8. skills-engine/ is itself a significant subsystem with clear boundaries: manifest parsing, file operations, path remapping, replay/migration logic, locking, and state management. It is tested heavily under skills-engine/__tests__/, which suggests the project treats skill application as a versioned, stateful transformation pipeline rather than simple file copying.

9. There is a second orchestration surface under setup/ and scripts/. setup/ drives first-time installation and environment validation, while scripts/ contains maintenance commands such as skill drift fixes, migrations, validation, and uninstall flows. These are operational tools around the core runtime, not part of the agent loop itself.

10. The web dashboard in src/web/ is a read-only observability layer. It serves dashboard.html and exposes event parsing/transcript views, giving users a live view of agent activity and container logs. This is separate from message channels and is used for monitoring, not task ingress.

11. Data flow is generally: external channel or stdin JSON → host router/scheduler → persistent state in SQLite → container runner → agent runner in isolated container → scientific tools and generated files → results streamed back through stdout or channel adapters. Session/group concepts (src/group-folder.ts, src/group-queue.ts, groups/) keep conversations and artifacts partitioned.

12. Operationally, the repo also contains many packaged examples under examples/ and documentation under docs/. These are not runtime subsystems, but they show the intended output shape: complete, reproducible materials workflows with inputs, logs, plots, and post-processing artifacts.

13. For an architecture diagram, the key boundaries to show are: external communication adapters, host orchestration and persistence, container isolation, and in-container agent/tool execution. The skills system spans both authoring and runtime knowledge, while the web dashboard and setup scripts are supporting surfaces around the main agent pipeline.