metabolism-tools/workspace-metabolism

MCP server and CLI for workspace metabolism: human-authored lifecycle rules
keep agent workspaces useful across runs through policy-bounded cleanup,
verified restore and an auditable history. Python 3.11+, **zero dependencies**,
Windows / Linux / macOS.
▶️ Watch the 60-second GIF demo · try the
interactive workspace-metabolism demo (download it
and open it in a browser).
The problem
AI coding agents (Claude Code, Codex, DeepSeek Harness, …) share one thing —
your workspace — and they leave a trail of scratch files, caches and staged
directories behind. Nobody owns the cleanup: deleting by hand is irreversible,
scheduled scripts have no audit trail, and the next agent run works in the
garbage the last one left.
workspace-metabolism is the **policy layer** for that: one metabolism.json
decides what every path is worth (G1 never touch → G4 auto), nothing is ever
deleted by pattern — items move to a recycle area with per-file SHA-256 hashes
and rollback restores them exactly — and every action lands in a
**hash-chained journal** that verify can audit.
**Try it in 30 seconds:**
**Distribution (v0.8.0):** GitHub release and installable wheel.
GitHub and PyPI publication are verified separately. Use the exact release wheel below.
See v0.8.0 release notes for installation.
The current source is **0.8.0**. To run its recovery and
maintenance checks from source, clone this release and run python -m pip install -e ..
Use wm doctor --json to confirm the version, Python executable and module
location actually in use. See upgrade notes.
Listed in awesome-mcp-servers under Developer Tools (merged 2026-09-21).
See the Glama tool-definition assessment
for interface quality; it does not establish production reliability or lower supervision.
Honest: no large production deployments yet, and the policy schema may shift
before v1.0. Early adopters are welcome to break it on weird directory
structures.
**Honest boundaries** — what this is *not*:
- **Not a sandbox.** wm gate is a governance/audit layer for cooperative
agents; a compromised or malicious agent can bypass it and call the target
server directly. OS-level sandboxing is a different layer.
- **Not a heuristic classifier.** It never decides "this file is garbage" on
its own — only the policy you approved decides. doctor only *suggests*
entries; nothing is governed until you adopt them.
- **Does not fix agent bugs.** It governs the byproducts agents leave; it does
not stop agents from producing them.
- **Local audit, not a notary.** The hash-chained journal detects tampering
with the tool's own records; it is not a distributed or court-grade ledger.
This repo has two linked ideas:
- **Agentic Metabolic Engineering** is the method: how to think about workspace lifecycle.
- **AI governance as code** is the implementation: how wm applies that method with policy files and commands.
中文快速上手（30 秒）
**v0.6.0 新增**：先认领再写入、清理避让未完成认领、精确绑定 SQLite 路径及不建库的只读
检查。复用现有任务和数据入口，不另建 AI 调度系统。见接入指南、
认领使用说明和数据库检查。
AI 编程（Claude Code / Codex / Aider 等）会在工作区留下大量草稿、缓存和
废弃文件，越堆越多，下一轮 AI 还得在垃圾堆里干活。这个工具用一份策略文件
管理文件的整个生命周期：**检查（只读）→ 回收（可回滚）→ 验证（防篡改记录）
→ 清理**。
默认只读、绝不直接删文件；每步操作都有防篡改记录；Windows / Mac / Linux 通用。
项目处于早期，认领和受控编辑仍为实验能力；策略格式在 v1.0 前可能调整。完整英文文档见下文。
Why this exists
Most disk tools either show you space (ncdu, duf) or delete things
(rmlint). workspace-metabolism is different: a **policy file** defines what
every path is worth (grades G1–G4), and the tool only ever does what the policy
allows — nothing more. It is the **policy layer for multi-agent workspaces**:
Claude Code, Codex, Aider, OpenClaw and every other agent share one thing —
your workspace — and the policy governs the byproducts all of them leave
behind, regardless of which tool created them. It fixes no vendor and judges
no file; see What this is not before you judge it.
- **G1 never touch** / **G2 keep** / **G3 approve + reference check** / **G4 auto**
- Deletion is never direct: items move to a recycle area, then rollback
restores them after a per-file SHA-256 integrity check
- Every action lands in a **hash-chained journal**; verify detects any edit
- Read-only audit reports candidates, unregistered paths, disk alerts, growth
trend and possible duplicates — plus residue on **memory-backed mounts**
(tmpfs/ramfs: it costs RAM, not just disk)
- Optional **protected window** (e.g. trading hours, business hours) during
which marked entries are never touched
- Scheduled runs are supported out of the box on Windows (Task Scheduler) and