zclean

zclean
AI coding runtime hygiene

What zclean is

zclean is a zero-dependency CLI that keeps AI coding sessions from leaving runtime mess behind.

It helps with two local hygiene problems:

1. Zombie AI runtime processes. Orphaned MCP servers, sub-agents, headless browsers, package runners, sandboxes, and dev servers left behind by Claude Code, Codex, Cursor-style agents, Windsurf, and other AI coding tools.

2. Safe workspace cache cleanup. Common project cache directories such as .next/cache, .turbo, .vite, .parcel-cache, node_modules/.cache, .pytest_cache, .ruff_cache, .mypy_cache, and Python __pycache__.

It is local-only, dry-run first, and requires --yes before destructive cleanup.

What zclean is not

zclean is not an app uninstaller, system optimizer, disk map, telemetry agent, or whole-disk cleaner. It does not crawl your entire Mac, delete documents, remove applications, or touch arbitrary folders.

The goal is narrower: AI coding cleanup and developer workspace hygiene.

Quick Start

npm install -g @thestackai/zclean
zclean init

One-off dry run without installation:

npx --yes @thestackai/zclean

Review before cleaning:

zclean report
zclean report --json

Clean only when you decide:

zclean --yes
zclean cache --yes

Why developers use it

AI coding tools spawn many short-lived runtimes while they work:

• MCP servers
• Claude Code sub-agents
• Codex sandboxes
• headless Chromium or Playwright sessions
• npm exec, tsx, bun, deno, and Python helpers
• build watchers such as Vite, Next.js, webpack, and esbuild

When an agent crashes, a terminal closes, or a session ends abruptly, those child processes can keep running. They hold memory, ports, file handles, and CPU. zclean finds them, explains why they are candidates, and cleans them only when the safety checks pass.

Core commands

Runtime cleanup

Dry run:

zclean

Example output:

zclean - scanning for zombie processes...

Found 12 zombie processes:

  PID 26413  node      367 MB  18h  claude mcp-server
  PID 62830  chrome    200 MB   3h  agent-browser
  PID 26221  npm       142 MB   2d  npm exec task-master-ai

Total memory reclaimable: 2.4 GB
Run zclean --yes to clean up these processes.

Actual cleanup:

zclean --yes

Safety rules:

• Manual scans are dry-run by default.
• Cleanup requires --yes.
• Active parent sessions are protected.
• tmux, screen, PM2, Forever, Docker, and VS Code child processes are skipped.
• PID identity is re-verified before every kill to avoid PID recycling accidents.
• Process enumeration failures are reported as errors, not as a fake "clean" state.

Workspace cache cleanup

Dry run:

zclean cache

Clean supported cache directories:

zclean cache --yes

Scan another workspace:

zclean cache --path=/path/to/project

Supported default cache targets:

zclean cache --json emits relative paths only. It does not expose absolute local paths and does not remove anything unless --yes is present.

Report and JSON surfaces

zclean report --json is designed for scripts, CI notes, local dashboards, and other agents:

zclean report --json

The report includes:

• schemaVersion: 1
• AI runtime hygiene status
• candidate count and reclaimable memory
• top candidates by risk
• scan warnings and errors
• cleanup history summary
• safety guardrails
• recommended next actions

Raw command lines and local filesystem paths are omitted from public JSON surfaces.

History, protection, and doctor

Machine-readable history:

zclean history --json

Protection list management:

zclean protect list
zclean protect add "mcp-server-keep"
zclean protect remove "mcp-server-keep"

Health checks:

zclean doctor
zclean doctor --json

doctor --json exits 0 only when the setup is healthy. Warnings and errors exit 1 so automation can treat non-healthy states honestly.

Configuration

~/.zclean/config.json:

{
  "whitelist": [],
  "maxAge": "24h",
  "memoryThreshold": "500MB",
  "maxKillBatch": 20,
  "sigterm_timeout": 10,
  "dryRunDefault": true,
  "logRetention": "30d",
  "customAiDirs": []
}

Supported tools

Platform status

FAQ

Will zclean kill my running Claude Code session?

Manual and scheduled scans protect active sessions by checking whether the parent process is alive. The Claude Code SessionEnd hook passes --session-pid so cleanup is scoped to descendants of the session that just ended.

Will zclean delete my project files?

No. Runtime cleanup kills verified zombie processes. Cache cleanup only removes supported cache directories and only with zclean cache --yes.

Is zclean a general Mac cleaner?

No. zclean focuses on AI coding runtime cleanup and safe developer workspace cache cleanup. It does not uninstall apps, draw disk maps, or scan the whole disk.

Does the scheduler slow my machine?

No. The scheduler runs a single scan and exits. There is no persistent background daemon.

How do I remove zclean?

zclean uninstall
npm uninstall -g @thestackai/zclean

If you only used npx --yes @thestackai/zclean, there is no global package to uninstall.

Contributing

See CONTRIBUTING.md.

Adding a process pattern? Edit src/detector/patterns.js.

Adding a cache target? Keep it deterministic, workspace-scoped, and dry-run first.

License

MIT - see LICENSE.

Built by TheStack-ai.