{"id":48085256,"url":"https://github.com/TheStack-ai/zclean","last_synced_at":"2026-04-20T01:00:55.507Z","repository":{"id":345048141,"uuid":"1183971506","full_name":"TheStack-ai/zclean","owner":"TheStack-ai","description":"Kill zombie processes left by AI coding tools — automatic memory cleaner for Claude Code, Codex, and Cursor","archived":false,"fork":false,"pushed_at":"2026-04-02T08:11:23.000Z","size":474,"stargazers_count":28,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T14:41:49.609Z","etag":null,"topics":["ai-coding","claude-code","cleanup","cli","codex","cursor","developer-tools","linux","macos","memory","nodejs","npx","orphan-process","process-cleaner","ram","system-cleanup","windsurf","zombie-process"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@thestackai/zclean","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheStack-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-17T05:54:24.000Z","updated_at":"2026-04-02T08:11:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TheStack-ai/zclean","commit_stats":null,"previous_names":["whynowlab/zclean","thestack-ai/zclean"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TheStack-ai/zclean","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheStack-ai%2Fzclean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheStack-ai%2Fzclean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheStack-ai%2Fzclean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheStack-ai%2Fzclean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheStack-ai","download_url":"https://codeload.github.com/TheStack-ai/zclean/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheStack-ai%2Fzclean/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32028547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"ssl_error","status_checked_at":"2026-04-20T00:17:31.068Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","claude-code","cleanup","cli","codex","cursor","developer-tools","linux","macos","memory","nodejs","npx","orphan-process","process-cleaner","ram","system-cleanup","windsurf","zombie-process"],"created_at":"2026-04-04T15:14:13.317Z","updated_at":"2026-04-20T01:00:55.501Z","avatar_url":"https://github.com/TheStack-ai.png","language":"JavaScript","readme":"# zclean — Zombie Process Cleaner for AI Coding Tools\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cpre\u003e\n███████  ██████ ██      ███████  █████  ███    ██\n╚══███  ██      ██      ██      ██   ██ ████   ██\n  ███   ██      ██      █████   ███████ ██ ██  ██\n ███    ██      ██      ██      ██   ██ ██  ██ ██\n███████  ██████ ███████ ███████ ██   ██ ██   ████\n\u003c/pre\u003e\n\n**Stop AI coding tools from eating your RAM.**\n\n[![npm version](https://img.shields.io/npm/v/@thestackai/zclean?style=flat-square\u0026color=blue)](https://www.npmjs.com/package/@thestackai/zclean)\n[![npm downloads](https://img.shields.io/npm/dm/@thestackai/zclean?style=flat-square\u0026color=brightgreen)](https://www.npmjs.com/package/@thestackai/zclean)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square\u0026logo=node.js\u0026logoColor=white)](#)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square)](#)\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-blue?style=flat-square)](#)\n[![Tests](https://img.shields.io/badge/tests-58%20passing-brightgreen?style=flat-square)](#)\n[![GitHub stars](https://img.shields.io/github/stars/TheStack-ai/zclean?style=flat-square)](https://github.com/TheStack-ai/zclean)\n[![Mentioned in Awesome Claude Code Toolkit](https://awesome.re/mentioned-badge.svg)](https://github.com/rohitg00/awesome-claude-code-toolkit)\n\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo.gif\" alt=\"zclean demo\" width=\"600\"\u003e\n\u003c/p\u003e\n\n---\n\n## Quick Demo\n\nAI coding tools spawn child processes — MCP servers, sub-agents, headless browsers, build watchers. When the session ends or crashes, those children don't always exit. They pile up silently, draining RAM until your machine grinds to a halt.\n\n**Before**\n\n```\n$ zclean\n\n  zclean — scanning for zombie processes...\n\n  Found 12 zombie processes:\n\n    PID 26413  node         367 MB  (orphan, 18h)  was: claude mcp-server\n    PID 62830  chrome       200 MB  (orphan, 3h)   was: agent-browser\n    PID 26221  npm          142 MB  (orphan, 2d)   was: npm exec task-master-ai\n    PID 23096  node         355 MB  (orphan, 6h)   was: claude sub-agent\n    ... 8 more\n\n  Total: 12 zombies, ~2.4 GB reclaimable\n\n  Run `zclean --yes` to clean.\n```\n\n**After**\n\n```\n$ zclean --yes\n\n  zclean — scanning for zombie processes...\n\n  Cleaned 12 zombie processes. Reclaimed ~2.4 GB.\n\n  zclean status:\n    Protection: active\n    SessionEnd hook: registered\n    Hourly scheduler: running\n```\n\n## Why zclean?\n\nClaude Code, Codex, and other AI coding tools spawn dozens of child processes per session: MCP servers, sub-agents, headless Chromium instances, esbuild watchers, and more. When the parent session exits — especially on crash or force-quit — these children become orphans.\n\nThey keep running. They keep consuming RAM. Your machine gets slower day by day, and you blame the AI tool when the real culprit is zombie processes nobody cleaned up.\n\n`zclean` fixes this automatically. Install once, forget about it.\n\n## Install\n\n```bash\nnpx z-clean init\n```\n\nThat's it. This command:\n1. Detects your OS (macOS / Linux / Windows)\n2. Registers a Claude Code `SessionEnd` hook for instant cleanup\n3. Sets up an hourly background scan as a safety net\n4. Creates your config at `~/.zclean/config.json`\n\n## How it works\n\n**Layer 1 — SessionEnd Hook**\nWhen a Claude Code session ends, `zclean` immediately cleans up that session's orphaned children. Fast and targeted.\n\n**Layer 2 — Hourly Scheduler**\nA lightweight background scan catches anything the hook missed: crash leftovers, Codex orphans, stale browser daemons, and processes from tools that don't support hooks.\n\nTogether, these two layers keep your system clean without you ever thinking about it.\n\n## Safety\n\n`zclean` follows one rule: **if the parent is alive, don't touch it.**\n\n- Scans are **dry-run by default** — you see what would be cleaned before anything happens\n- Only targets **known AI tool process patterns** (MCP servers, agent browsers, sub-agents, build zombies)\n- **Whitelist support** — protect any process you want to keep\n- **Skips** tmux/screen sessions, PM2/Forever daemons, Docker containers, VS Code children\n- **Re-verifies** PID identity before every kill (prevents PID recycling accidents)\n- Logs every action with full command line for manual recovery\n\nYour `node server.js` running in a terminal tab? Untouched. Your `vite dev` in tmux? Untouched. Only true orphans from dead AI sessions get cleaned.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `zclean` | Scan for zombies (dry-run, shows what would be cleaned) |\n| `zclean --yes` | Scan and clean zombie processes |\n| `zclean init` | Install SessionEnd hook + hourly scheduler |\n| `zclean status` | Show protection status and cleanup history |\n| `zclean logs` | View detailed cleanup log |\n| `zclean config` | Show current configuration |\n| `zclean uninstall` | Remove all hooks and schedulers |\n\n## Configuration\n\n`~/.zclean/config.json`:\n\n```json\n{\n  \"whitelist\": [],\n  \"maxAge\": \"24h\",\n  \"memoryThreshold\": \"500MB\",\n  \"maxKillBatch\": 20,\n  \"schedule\": \"hourly\",\n  \"sigterm_timeout\": 10,\n  \"dryRunDefault\": true,\n  \"logRetention\": \"30d\",\n  \"customAiDirs\": []\n}\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `whitelist` | `[]` | Process name patterns to never kill |\n| `maxAge` | `\"24h\"` | Kill orphan `node`/`esbuild` only after this age |\n| `memoryThreshold` | `\"500MB\"` | Flag orphans above this RAM usage regardless of age |\n| `maxKillBatch` | `20` | Max processes to kill per invocation (safety limit) |\n| `sigterm_timeout` | `10` | Seconds to wait after SIGTERM before SIGKILL |\n| `dryRunDefault` | `true` | Manual `zclean` runs in dry-run mode |\n| `customAiDirs` | `[]` | Additional AI tool directories to detect (e.g. `[\".mytool\"]`) |\n\n## FAQ\n\n### Will this kill my running Claude Code session?\nNo. `zclean` checks if the parent process is alive. Active sessions and their children are always protected.\n\n### What about my `vite dev` / `next dev` server?\nIf you started it in a terminal, tmux, or VS Code — it has a living parent and won't be touched. Only orphaned dev servers (parent process dead for 24h+) are candidates.\n\n### Does the hourly scheduler slow my machine?\nNo. It runs a single process scan (~60ms), cleans if needed, and exits. No persistent daemon.\n\n### How do I stop zclean completely?\n```bash\nzclean uninstall\nnpm uninstall -g zclean\n```\n\n## Supported Tools\n\n| Tool | Cleanup Coverage |\n|------|-----------------|\n| Claude Code | MCP servers, sub-agents (`--print`), sessions (`--session-id`), agent-browser, playwright |\n| Codex | codex exec, codex-sandbox |\n| Aider | orphaned aider/python processes |\n| Gemini CLI | orphaned gemini processes |\n| Build tools | esbuild, vite, webpack, next dev (AI tool paths only) |\n| MCP servers | Any `mcp-server-*` pattern |\n| Runtimes | node, tsx, ts-node, bun, deno (AI tool paths only) |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nAdding a new process pattern? Edit `src/detector/patterns.js` and open a PR.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n# zclean — Zombie Process Cleaner for AI Coding Tools\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt by [thestack-ai](https://github.com/thestack-ai) — the team behind [Swing](https://github.com/thestack-ai/swing-skills).\n\n\u003c/div\u003e\n","funding_links":[],"categories":["Ecosystem"],"sub_categories":["Quick Setup with cc-safe-setup"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheStack-ai%2Fzclean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTheStack-ai%2Fzclean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheStack-ai%2Fzclean/lists"}