DEV Community

thestack_ai
thestack_ai

Posted on

I built zclean to clean up zombie processes left by AI coding tools

#ai #opensource #javascript #tools

zclean hero

AI coding tools are great until yesterday's agent session is still running today.

After long Claude Code, Codex, Cursor, Windsurf, or MCP-heavy sessions, I kept seeing the same kind of local runtime residue:

  • orphaned node and Python helper processes
  • stale MCP servers
  • forgotten dev servers
  • headless browser or Playwright workers
  • package-runner processes from npm exec, tsx, bun, or similar tools
  • project caches from Next.js, Vite, Turborepo, pytest, Ruff, and mypy

None of this is dramatic by itself. But after a few days of agent-heavy work, those leftovers can hold memory, ports, CPU, and file handles. The frustrating part is that the machine just feels slower, and it is not obvious which process is safe to kill.

So I built zclean.

GitHub: https://github.com/TheStack-ai/zclean

npm: https://www.npmjs.com/package/@thestackai/zclean

What zclean does

zclean is a local-only CLI for AI coding runtime hygiene.

It focuses on two narrow problems:

  1. Finding zombie or orphaned runtime processes left by AI coding tools.
  2. Finding safe workspace cache directories that are commonly produced during coding-agent sessions.

It is not a full disk cleaner. It is not an app uninstaller. It does not crawl your whole machine. It is intentionally scoped to developer runtime leftovers.

The default behavior is dry-run first.

npx --yes @thestackai/zclean report
Enter fullscreen mode Exit fullscreen mode

If you want to inspect workspace caches:

npx --yes @thestackai/zclean cache
Enter fullscreen mode Exit fullscreen mode

Cleanup requires explicit confirmation:

npx --yes @thestackai/zclean --yes
npx --yes @thestackai/zclean cache --yes
Enter fullscreen mode Exit fullscreen mode

Why not just use a generic cleanup app?

Generic cleanup tools usually think in broad categories: disk space, browser cache, app leftovers, system junk.

That is useful, but it is not the same problem.

AI coding tools create a more specific kind of mess:

  • an MCP server launched for one coding session
  • a browser worker attached to an agent task
  • a dev server whose parent terminal closed
  • a package-runner process from an interrupted automation
  • caches generated by repeated agent edits and test runs

Those need context. A safe cleaner should explain why something is a candidate before it touches anything.

That is the core idea behind zclean: report first, clean only when the user asks.

Example workflow

Start with a report:

zclean report
Enter fullscreen mode Exit fullscreen mode

Or get JSON for scripts, local dashboards, or other agents:

zclean report --json
Enter fullscreen mode Exit fullscreen mode

Inspect cleanup history:

zclean history --json
Enter fullscreen mode Exit fullscreen mode

Protect patterns you do not want touched:

zclean protect add "my-important-worker"
zclean protect list
Enter fullscreen mode Exit fullscreen mode

Check installation, scheduler, config, and process enumeration health:

zclean doctor
zclean doctor --json
Enter fullscreen mode Exit fullscreen mode

What it tries to avoid

Process cleanup is risky if you are careless.

zclean tries to stay conservative:

  • manual scans are dry-run by default
  • destructive cleanup requires --yes
  • active parent sessions are protected
  • common long-running process managers are skipped
  • process identity is re-verified before kill
  • process enumeration failures are reported instead of silently pretending the system is clean
  • JSON output avoids exposing raw local paths and raw command lines

That last point matters if you pipe reports into dashboards, issue comments, or agent workflows.

Workspace cache cleanup

The cache command targets common project cache directories:

  • .next/cache
  • .nuxt
  • .turbo
  • .vite
  • .parcel-cache
  • node_modules/.cache
  • .pytest_cache
  • .ruff_cache
  • .mypy_cache
  • __pycache__

Dry-run:

zclean cache
Enter fullscreen mode Exit fullscreen mode

Clean:

zclean cache --yes
Enter fullscreen mode Exit fullscreen mode

Scan a specific project:

zclean cache --path=/path/to/project
Enter fullscreen mode Exit fullscreen mode

Again, this is intentionally not whole-disk cleanup. It is workspace hygiene.

Why I open-sourced it

AI coding tools are becoming part of the normal development loop. That means the local runtime environment around them also needs better hygiene.

The problem is small, but persistent:

"Why is my laptop slow after a long AI coding session?"

Sometimes the answer is simply: old agent runtimes are still alive.

If you want to try it:

npx --yes @thestackai/zclean report
Enter fullscreen mode Exit fullscreen mode

Repository:

https://github.com/TheStack-ai/zclean

Package:

https://www.npmjs.com/package/@thestackai/zclean

If you use Claude Code, Codex, Cursor, Windsurf, MCP servers, or browser-based coding agents heavily, I would be interested to hear what kinds of runtime leftovers you see.

Top comments (0)