@ekaone/killx

Zero-dependency cross-platform process tree killer.

Features

• 🔪 Kill a process and all its children recursively
• 🧪 Dry-run mode — preview without killing
• 🌳 Inspect the full process tree
• ⚡ Signal strategy — escalate from SIGTERM → SIGKILL
• 📦 Zero runtime dependencies
• 🖥️ Works on Linux, macOS, Windows
• 🔧 Promise-based API + CLI
• 📄 Structured JSON output

Install

# As a dependency
pnpm add @ekaone/killx

# Global CLI
pnpm add -g @ekaone/killx

yarn global add @ekaone/killx

npm install -g @ekaone/killx

CLI Usage

# Kill process + all children
killx 1234

# Preview without killing
killx 1234 --dry-run

# Send specific signal
killx 1234 --signal SIGKILL

# Force kill (SIGTERM → SIGKILL escalation)
killx 1234 --force

# JSON output
killx 1234 --json

# Inspect process tree
killx tree 1234
killx inspect 1234 --json

Example Output

Killed:
  - 1235 (node)
  - 1234 (npm)

{
  "success": true,
  "killed": [
    { "pid": 1235, "name": "node" },
    { "pid": 1234, "name": "npm" }
  ]
}

Programmatic API

killx(pid, options?)

import { killx } from "@ekaone/killx";

// Simple kill
const result = await killx(1234);

// Dry run
const preview = await killx(1234, { dryRun: true });

// Force with escalation
const forced = await killx(1234, { force: true, timeout: 3000 });

// Custom strategy
const strategic = await killx(1234, {
  strategy: [
    { signal: "SIGTERM", wait: 2000 },
    { signal: "SIGKILL" },
  ],
});

// Filter specific processes
const filtered = await killx(1234, {
  filter: (proc) => proc.pid !== 9999,
});

KillOptions

| Option | Type | Default | Description | |------------|--------------------------|-------------|------------------------------------------| | signal | NodeJS.Signals\|number | "SIGTERM" | Signal to send | | dryRun | boolean | false | Preview only, do not kill | | force | boolean | false | Escalate to SIGKILL after timeout | | timeout | number | 3000 | ms to wait before SIGKILL (with force) | | strategy | SignalStep[] | — | Multi-step escalation override | | filter | (proc) => boolean | — | Skip processes returning false |

KillResult

type KillResult = {
  success: boolean;
  killed: ProcessInfo[];
  skipped?: ProcessInfo[];
  failed?: { pid: number; error: string }[];
  dryRun?: boolean;
};

inspect(pid)

Returns the full process tree.

import { inspect } from "@ekaone/killx";

const tree = inspect(1234);
// {
//   pid: 1234,
//   name: "node",
//   children: [
//     { pid: 1235, name: "worker" }
//   ]
// }

Design Principles

• Safe by default — SIGTERM first, opt-in to SIGKILL
• Dry-run first — always preview before kill
• JSON-first — structured output for piping
• No hidden side effects — what you call is what happens
• Minimal — no framework, no deps, just Node.js primitives

License

MIT © Eka Prasetia

Links

• npm Package
• GitHub Repository
• Issue Tracker

⭐ If this library helps you, please consider giving it a star on GitHub!