z-clean 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 whynowlab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+<div align="center">
+
+<pre>
+███████  ██████ ██      ███████  █████  ███    ██
+╚══███  ██      ██      ██      ██   ██ ████   ██
+  ███   ██      ██      █████   ███████ ██ ██  ██
+ ███    ██      ██      ██      ██   ██ ██  ██ ██
+███████  ██████ ███████ ███████ ██   ██ ██   ████
+</pre>
+
+**Stop AI coding tools from eating your RAM.**
+
+[![npm version](https://img.shields.io/npm/v/@thestackai/zclean?style=flat-square&color=blue)](https://www.npmjs.com/package/@thestackai/zclean)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square)](#)
+
+</div>
+
+<p align="center">
+  <img src="assets/demo.gif" alt="zclean demo" width="600">
+</p>
+
+---
+
+## Quick Demo
+
+AI 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.
+
+**Before**
+
+```
+$ zclean
+
+  zclean — scanning for zombie processes...
+
+  Found 12 zombie processes:
+
+    PID 26413  node         367 MB  (orphan, 18h)  was: claude mcp-server
+    PID 62830  chrome       200 MB  (orphan, 3h)   was: agent-browser
+    PID 26221  npm          142 MB  (orphan, 2d)   was: npm exec task-master-ai
+    PID 23096  node         355 MB  (orphan, 6h)   was: claude sub-agent
+    ... 8 more
+
+  Total: 12 zombies, ~2.4 GB reclaimable
+
+  Run `zclean --yes` to clean.
+```
+
+**After**
+
+```
+$ zclean --yes
+
+  zclean — scanning for zombie processes...
+
+  Cleaned 12 zombie processes. Reclaimed ~2.4 GB.
+
+  zclean status:
+    Protection: active
+    SessionEnd hook: registered
+    Hourly scheduler: running
+```
+
+## Why zclean?
+
+Claude 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.
+
+They 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.
+
+`zclean` fixes this automatically. Install once, forget about it.
+
+## Install
+
+```bash
+npx zclean init
+```
+
+That's it. This command:
+1. Detects your OS (macOS / Linux / Windows)
+2. Registers a Claude Code `SessionEnd` hook for instant cleanup
+3. Sets up an hourly background scan as a safety net
+4. Creates your config at `~/.zclean/config.json`
+
+## How it works
+
+**Layer 1 — SessionEnd Hook**
+When a Claude Code session ends, `zclean` immediately cleans up that session's orphaned children. Fast and targeted.
+
+**Layer 2 — Hourly Scheduler**
+A lightweight background scan catches anything the hook missed: crash leftovers, Codex orphans, stale browser daemons, and processes from tools that don't support hooks.
+
+Together, these two layers keep your system clean without you ever thinking about it.
+
+## Safety
+
+`zclean` follows one rule: **if the parent is alive, don't touch it.**
+
+- Scans are **dry-run by default** — you see what would be cleaned before anything happens
+- Only targets **known AI tool process patterns** (MCP servers, agent browsers, sub-agents, build zombies)
+- **Whitelist support** — protect any process you want to keep
+- **Skips** tmux/screen sessions, PM2/Forever daemons, Docker containers, VS Code children
+- **Re-verifies** PID identity before every kill (prevents PID recycling accidents)
+- Logs every action with full command line for manual recovery
+
+Your `node server.js` running in a terminal tab? Untouched. Your `vite dev` in tmux? Untouched. Only true orphans from dead AI sessions get cleaned.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `zclean` | Scan for zombies (dry-run, shows what would be cleaned) |
+| `zclean --yes` | Scan and clean zombie processes |
+| `zclean init` | Install SessionEnd hook + hourly scheduler |
+| `zclean status` | Show protection status and cleanup history |
+| `zclean logs` | View detailed cleanup log |
+| `zclean config` | Show current configuration |
+| `zclean uninstall` | Remove all hooks and schedulers |
+
+## Configuration
+
+`~/.zclean/config.json`:
+
+```json
+{
+  "whitelist": [],
+  "maxAge": "24h",
+  "memoryThreshold": "500MB",
+  "schedule": "hourly",
+  "sigterm_timeout": 10,
+  "dryRunDefault": true,
+  "logRetention": "30d"
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `whitelist` | `[]` | Process name patterns to never kill |
+| `maxAge` | `"24h"` | Kill orphan `node`/`esbuild` only after this age |
+| `memoryThreshold` | `"500MB"` | Flag orphans above this RAM usage regardless of age |
+| `sigterm_timeout` | `10` | Seconds to wait after SIGTERM before SIGKILL |
+| `dryRunDefault` | `true` | Manual `zclean` runs in dry-run mode |
+
+## FAQ
+
+### Will this kill my running Claude Code session?
+No. `zclean` checks if the parent process is alive. Active sessions and their children are always protected.
+
+### What about my `vite dev` / `next dev` server?
+If 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.
+
+### Does the hourly scheduler slow my machine?
+No. It runs a single process scan (~100ms), cleans if needed, and exits. No persistent daemon.
+
+### How do I stop zclean completely?
+```bash
+zclean uninstall
+npm uninstall -g zclean
+```
+
+## Supported Tools
+
+| Tool | Cleanup Coverage |
+|------|-----------------|
+| Claude Code | MCP servers, sub-agents, agent-browser, playwright |
+| Codex | codex exec, background node workers |
+| Build tools | esbuild, vite, webpack, next dev (orphaned only) |
+| MCP servers | Any `mcp-server-*` pattern |
+| Runtimes | node, tsx, ts-node, bun, deno, python (AI tool paths only) |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+Adding a new process pattern? Edit `src/detector/patterns.js` and open a PR.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<div align="center">
+
+Built by [whynowlab](https://github.com/whynowlab) — the team behind [Swing](https://github.com/whynowlab/swing-skills).
+
+</div>

package/bin/zclean.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+'use strict';
+
+const os = require('os');
+const { scan } = require('../src/scanner');
+const { killZombies } = require('../src/killer');
+const { loadConfig, saveConfig, readLogs, pruneLogs, CONFIG_FILE, DEFAULT_CONFIG, appendLog } = require('../src/config');
+const { reportDryRun, reportKill, reportStatus, reportLogs, reportConfig, c, bold } = require('../src/reporter');
+const { installHook, removeHook } = require('../src/installer/hook');
+
+// Platform-specific installers (lazy loaded)
+const platform = os.platform();
+
+// ─── CLI Argument Parsing ───────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const flags = {};
+const positional = [];
+
+for (const arg of args) {
+  if (arg.startsWith('--')) {
+    const [key, value] = arg.substring(2).split('=');
+    flags[key] = value !== undefined ? value : true;
+  } else if (arg.startsWith('-') && arg.length === 2) {
+    flags[arg.substring(1)] = true;
+  } else {
+    positional.push(arg);
+  }
+}
+
+const command = positional[0] || null;
+
+// ─── Version / Help ─────────────────────────────────────────────────────────
+
+if (flags.version || flags.v) {
+  const pkg = require('../package.json');
+  console.log(`zclean v${pkg.version}`);
+  process.exit(0);
+}
+
+if (flags.help || flags.h) {
+  printHelp();
+  process.exit(0);
+}
+
+// ─── Command Dispatch ───────────────────────────────────────────────────────
+
+async function main() {
+  const config = loadConfig();
+
+  switch (command) {
+    case 'init':
+      return cmdInit(config);
+
+    case 'status':
+      return cmdStatus(config);
+
+    case 'logs':
+      return cmdLogs(config);
+
+    case 'uninstall':
+      return cmdUninstall();
+
+    case 'config':
+      return cmdConfig(config);
+
+    case null:
+      // Default: scan (dry-run unless --yes)
+      return cmdScan(config);
+
+    default:
+      console.error(c('red', `  Unknown command: ${command}`));
+      printHelp();
+      process.exit(1);
+  }
+}
+
+// ─── Commands ───────────────────────────────────────────────────────────────
+
+/**
+ * Default command: scan for zombies.
+ * Dry-run unless --yes is passed.
+ */
+function cmdScan(config) {
+  const sessionPid = flags['session-pid'] ? parseInt(flags['session-pid'], 10) : null;
+  const force = flags.yes || flags.y;
+
+  console.log(bold('\n  zclean') + c('gray', ' — scanning for zombie processes...\n'));
+
+  const zombies = scan(config, { sessionPid });
+
+  if (force) {
+    // Kill mode
+    if (zombies.length === 0) {
+      console.log(c('green', '  No zombie processes found. System is clean.\n'));
+      appendLog({ action: 'scan', found: 0 });
+      return;
+    }
+    appendLog({ action: 'scan', found: zombies.length });
+    const results = killZombies(zombies, config);
+    reportKill(results);
+  } else {
+    // Dry-run mode
+    reportDryRun(zombies);
+    if (zombies.length > 0) {
+      appendLog({ action: 'dry-run', found: zombies.length });
+    }
+  }
+
+  // Prune old logs
+  pruneLogs(config);
+}
+
+/**
+ * init: Install hooks + scheduler.
+ */
+function cmdInit(config) {
+  console.log(bold('\n  zclean init') + c('gray', ' — installing hooks and scheduler...\n'));
+
+  // 1. Save default config if none exists
+  const existingConfig = loadConfig();
+  if (JSON.stringify(existingConfig) === JSON.stringify(DEFAULT_CONFIG)) {
+    saveConfig(DEFAULT_CONFIG);
+    console.log(c('green', '  Config created:') + ` ${CONFIG_FILE}`);
+  } else {
+    console.log(c('gray', '  Config exists:') + ` ${CONFIG_FILE}`);
+  }
+
+  // 2. Install Claude Code hook
+  const hookResult = installHook();
+  const hookIcon = hookResult.installed ? c('green', '  Hook:') : c('yellow', '  Hook:');
+  console.log(`${hookIcon} ${hookResult.message}`);
+
+  // 3. Install platform-specific scheduler
+  installScheduler();
+
+  console.log();
+}
+
+/**
+ * status: Show current zombies and last cleanup info.
+ */
+function cmdStatus(config) {
+  const zombies = scan(config);
+  const logs = readLogs(100);
+  reportStatus(zombies, logs);
+}
+
+/**
+ * logs: Show recent cleanup history.
+ */
+function cmdLogs(config) {
+  const logs = readLogs(50);
+  reportLogs(logs);
+}
+
+/**
+ * uninstall: Remove hooks + scheduler.
+ */
+function cmdUninstall() {
+  console.log(bold('\n  zclean uninstall') + c('gray', ' — removing hooks and scheduler...\n'));
+
+  // Remove hook
+  const hookResult = removeHook();
+  console.log(`  Hook: ${hookResult.message}`);
+
+  // Remove scheduler
+  uninstallScheduler();
+
+  console.log(c('gray', `\n  Config and logs preserved at ~/.zclean/`));
+  console.log(c('gray', `  To fully remove: rm -rf ~/.zclean\n`));
+}
+
+/**
+ * config: Show current config.
+ */
+function cmdConfig(config) {
+  reportConfig(config, CONFIG_FILE);
+}
+
+// ─── Platform Scheduler Install/Uninstall ───────────────────────────────────
+
+function installScheduler() {
+  switch (platform) {
+    case 'darwin': {
+      const { installLaunchd } = require('../src/installer/launchd');
+      const result = installLaunchd();
+      const icon = result.installed ? c('green', '  Scheduler:') : c('yellow', '  Scheduler:');
+      console.log(`${icon} ${result.message}`);
+      break;
+    }
+    case 'linux': {
+      const { installSystemd } = require('../src/installer/systemd');
+      const result = installSystemd();
+      const icon = result.installed ? c('green', '  Scheduler:') : c('yellow', '  Scheduler:');
+      console.log(`${icon} ${result.message}`);
+      break;
+    }
+    case 'win32': {
+      const { installTaskScheduler } = require('../src/installer/taskscheduler');
+      const result = installTaskScheduler();
+      const icon = result.installed ? c('green', '  Scheduler:') : c('yellow', '  Scheduler:');
+      console.log(`${icon} ${result.message}`);
+      break;
+    }
+    default:
+      console.log(c('yellow', `  Scheduler: Unsupported platform (${platform}). Install a cron job manually.`));
+  }
+}
+
+function uninstallScheduler() {
+  switch (platform) {
+    case 'darwin': {
+      const { removeLaunchd } = require('../src/installer/launchd');
+      const result = removeLaunchd();
+      console.log(`  Scheduler: ${result.message}`);
+      break;
+    }
+    case 'linux': {
+      const { removeSystemd } = require('../src/installer/systemd');
+      const result = removeSystemd();
+      console.log(`  Scheduler: ${result.message}`);
+      break;
+    }
+    case 'win32': {
+      const { removeTaskScheduler } = require('../src/installer/taskscheduler');
+      const result = removeTaskScheduler();
+      console.log(`  Scheduler: ${result.message}`);
+      break;
+    }
+    default:
+      console.log(c('yellow', `  Scheduler: Remove manually for ${platform}.`));
+  }
+}
+
+// ─── Help ───────────────────────────────────────────────────────────────────
+
+function printHelp() {
+  console.log(`
+  ${bold('zclean')} — Automatic zombie process cleaner for AI coding tools
+
+  ${bold('Usage:')}
+    zclean                Scan for zombies (dry-run)
+    zclean --yes          Scan and kill zombies
+    zclean init           Install hooks + scheduler
+    zclean status         Show current zombies and last cleanup
+    zclean logs           Show recent cleanup history
+    zclean uninstall      Remove hooks + scheduler
+    zclean config         Show current configuration
+
+  ${bold('Options:')}
+    --yes, -y             Kill found zombies (default: dry-run)
+    --session-pid=PID     Filter by parent session PID
+    --version, -v         Show version
+    --help, -h            Show this help
+
+  ${bold('Config:')}  ~/.zclean/config.json
+  ${bold('Logs:')}    ~/.zclean/history.jsonl
+
+  ${bold('Docs:')}    https://github.com/whynowlab/zclean
+`);
+}
+
+// ─── Run ────────────────────────────────────────────────────────────────────
+
+main().catch((err) => {
+  console.error(c('red', `\n  Error: ${err.message}\n`));
+  if (flags.verbose) {
+    console.error(err.stack);
+  }
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "z-clean",
+  "version": "0.1.1",
+  "description": "Automatic zombie process cleaner for AI coding tools (Claude Code, Codex)",
+  "bin": { "zclean": "./bin/zclean.js" },
+  "keywords": ["claude-code", "codex", "cleanup", "zombie", "orphan", "process", "ai-tools", "mcp"],
+  "author": "whynowlab",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/whynowlab/zclean.git" },
+  "engines": { "node": ">=18" },
+  "files": ["bin/", "src/", "LICENSE", "README.md"]
+}

package/src/config.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Config directory: ~/.zclean/
+const CONFIG_DIR = path.join(os.homedir(), '.zclean');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const LOG_FILE = path.join(CONFIG_DIR, 'history.jsonl');
+
+const DEFAULT_CONFIG = {
+  whitelist: [],
+  maxAge: '24h',
+  memoryThreshold: '500MB',
+  schedule: 'hourly',
+  sigterm_timeout: 10,
+  dryRunDefault: true,
+  logRetention: '30d',
+};
+
+/**
+ * Parse a duration string like "24h", "30d", "1h" into milliseconds.
+ */
+function parseDuration(str) {
+  const match = String(str).match(/^(\d+)\s*(ms|s|m|h|d)$/i);
+  if (!match) return null;
+  const value = parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
+  const multipliers = {
+    ms: 1,
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+  };
+  return value * multipliers[unit];
+}
+
+/**
+ * Parse a memory string like "500MB", "1GB" into bytes.
+ */
+function parseMemory(str) {
+  const match = String(str).match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)$/i);
+  if (!match) return null;
+  const value = parseFloat(match[1]);
+  const unit = match[2].toUpperCase();
+  const multipliers = { B: 1, KB: 1024, MB: 1024 * 1024, GB: 1024 * 1024 * 1024 };
+  return Math.floor(value * multipliers[unit]);
+}
+
+/**
+ * Ensure the config directory exists.
+ */
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Load config from disk, merging with defaults.
+ */
+function loadConfig() {
+  ensureConfigDir();
+  if (fs.existsSync(CONFIG_FILE)) {
+    try {
+      const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+      const userConfig = JSON.parse(raw);
+      return { ...DEFAULT_CONFIG, ...userConfig };
+    } catch {
+      // Corrupted config — use defaults
+      return { ...DEFAULT_CONFIG };
+    }
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+/**
+ * Save config to disk.
+ */
+function saveConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Append a log entry to the history file.
+ * Each entry is a JSON line with timestamp, action, and details.
+ */
+function appendLog(entry) {
+  ensureConfigDir();
+  const line = JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + '\n';
+  fs.appendFileSync(LOG_FILE, line, 'utf-8');
+}
+
+/**
+ * Read recent log entries (up to `limit`).
+ */
+function readLogs(limit = 50) {
+  if (!fs.existsSync(LOG_FILE)) return [];
+  try {
+    const lines = fs.readFileSync(LOG_FILE, 'utf-8').trim().split('\n').filter(Boolean);
+    return lines
+      .slice(-limit)
+      .map((line) => {
+        try { return JSON.parse(line); } catch { return null; }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Prune logs older than logRetention.
+ */
+function pruneLogs(config) {
+  const retentionMs = parseDuration(config.logRetention || '30d');
+  if (!retentionMs || !fs.existsSync(LOG_FILE)) return;
+
+  const cutoff = Date.now() - retentionMs;
+  const lines = fs.readFileSync(LOG_FILE, 'utf-8').trim().split('\n').filter(Boolean);
+  const kept = lines.filter((line) => {
+    try {
+      const entry = JSON.parse(line);
+      return new Date(entry.timestamp).getTime() >= cutoff;
+    } catch {
+      return false;
+    }
+  });
+  fs.writeFileSync(LOG_FILE, kept.join('\n') + (kept.length ? '\n' : ''), 'utf-8');
+}
+
+module.exports = {
+  CONFIG_DIR,
+  CONFIG_FILE,
+  LOG_FILE,
+  DEFAULT_CONFIG,
+  parseDuration,
+  parseMemory,
+  loadConfig,
+  saveConfig,
+  appendLog,
+  readLogs,
+  pruneLogs,
+  ensureConfigDir,
+};