workspace-metabolism is a policy-layer tool for governing AI coding agent workspaces, provided as an MCP server and CLI. It targets AI coding agents such as Claude Code, Codex, Aider, and OpenClaw that share the same workspace, governing the draft files, caches, and staging directories they leave behind.
Purpose AI coding agents leave large numbers of temporary files, caches, and abandoned directories in the workspace; manual deletion is irreversible, scheduled scripts lack audit records, and the next round of agents has to work amid the leftovers. workspace-metabolism manages the file lifecycle with a human-written policy file, keeping the workspace usable across multiple agent runs.
Main capabilities
- Policy tiers: a single metabolism.json determines the value tier of each path; G1 is never touched, G2 is retained, G3 requires approval and a reference check, and G4 is automatically cleaned up.
- Recoverable cleanup: never deletes directly by pattern; entries are moved into a recovery area and a per-file SHA-256 hash is recorded, so rollback can restore them precisely.
- Hash-chain audit log: every operation is written to a hash-chain log, and verify can detect any tampering.
- Read-only audit: reports candidate cleanup items, unregistered paths, disk alerts, growth trends, possible duplicates, and leftovers on memory mounts (tmpfs/ramfs).
- Protected time windows: you can set specific periods (such as trading hours or working hours) during which marked entries are not touched.
- Scheduled runs: supports Windows Task Scheduler and Linux/macOS cron via templates in examples/.
- Health score: wm health combines audit summaries into a score of 0-100, covering log auditability, governance, rot burden, and recovery readiness, and gives a grade of A-D.
- MCP server: wm mcp provides a zero-dependency MCP stdio server, allowing agents to initialize policy, audit, explain, verify, and dry-run cleanup plans on their own; clean executes only when the caller explicitly passes execute=true.
- AI governance: the optional ai_governance section checks before AI actions occur, and unknown actions are denied by default; wm gate wraps any MCP stdio server, checking every tools/call against policy, and denied calls do not reach the target.
- Database inspection: v0.6.0 Added claim-before-write, cleanup avoidance of incomplete claims, precise binding of SQLite paths, and read-only checks that do not create the database.
Usage
- Installation: use the v0.8.0 release wheel; to run from source, clone that release and execute python -m pip install -e .
- Initialization: wm init scans the workspace and registers common directories (source and docs are reserved as G2, logs/tmp/cache are automatic as G4, archive/staging are approved as G3). Edit metabolism.json and commit it like a source file. The tool automatically discovers metabolism.json or .wm.json at the workspace root.
- Preflight: wm doctor is a read-only preflight that reports whether the workspace and state directory are writable, whether the policy exists and is valid, and whether other wm operations hold the state lock. wm doctor --residue scans for ungoverned residue often left by agents, and --apply-policy can adopt suggestions into the policy.
- Cleanup: clean defaults to a dry run and requires --yes to execute; G4 requires --yes, G3 requires --approve and --approver.
- Verification and rollback: verify detects log tampering, and rollback restores a previous run from the recovery area.
- Integration: wm mcp can connect to MCP channels such as DeepSeek Harness; examples/micro_metabolism.py can connect to a session-end hook.
Applicable scenarios Suitable for teams where multiple AI coding agents share the same workspace and want to govern agent byproducts with a versioned, reviewable policy while retaining rollback-capable and auditable records. Also suitable for scenarios that require scheduled cleanup but demand an audit trail.
Limitations
- Not a sandbox: wm gate is a governance/audit layer for cooperative agents; a compromised or malicious agent can bypass the agent and call the target server directly.
- Not a heuristic classifier: it never decides on its own whether a file is junk, only an approved policy decides; doctor only suggests entries.
- Does not fix agent defects: it governs the byproducts left by agents, it does not prevent agents from producing them.
- Local audit rather than notarization: the hash-chain log detects tampering with the tool's own records, it is not a distributed or court-grade ledger.
- Early-stage project: there are no large-scale production deployments yet, and policy patterns may change before v1.0may change; claims and controlled editing are still experimental capabilities.
- Recovery does not free disk space: the log distinguishes planned bytes from actually moved bytes and records zero recovered bytes.
- Sensitive files are never automatically cleaned: the audit flags key/credential-type files, the policy validator refuses to register sensitive paths as G4, and clean skips candidates containing sensitive files.
