killpnpm

A focused pnpm process and agent diagnostics CLI.

The interactive UI is inspired by dense terminal dashboards like btop: bordered panes, high-contrast status blocks, fast keyboard control, and mouse-friendly row selection.

Run it with no arguments to open the interactive picker:

killpnpm

The picker shows:

• every running pnpm command
• where it was started from
• who started it
• inferred launcher/agent, such as Codex, Gemini, Claude, VS Code, Cursor, Warp, iTerm, Terminal, or You
• CPU and RAM used by the whole process group under that pnpm command
• how many matching processes are running
• process details like PID, process group, CPU, RAM, culprit, user, age, and command
• an Extra Info dashboard with disk usage, agent state footprint, pnpm cache/store footprint, top launcher, selected process-group blast radius, and scan limits

The Extra Info panel uses bounded background scans so the picker stays responsive. A + after a size means the scan hit a traversal limit and the value is a lower bound.

The TUI uses terminal-width breakpoints: stat cards, process columns, and key hints collapse before they wrap or spill off-screen.

Install

npm install -g killpnpm

If you already have a shell function or alias named killpnpm, remove or rename that shell entry first. Shell functions take precedence over globally installed npm binaries.

Usage

killpnpm                  # interactive picker
killpnpm dev              # kill pnpm commands matching "dev"
killpnpm --list           # list running pnpm commands
killpnpm --list --tree    # list commands and process group blast radius
killpnpm --agent Codex    # target pnpm commands launched by Codex
killpnpm --all            # select all running pnpm commands for kill
killpnpm --dry-run dev    # preview matches
killpnpm --signal INT dev # send SIGINT instead of SIGTERM
killpnpm --verify dev     # kill, then rescan the targeted process group
killpnpm --force-after 750 dev
                          # send SIGKILL to survivors after 750ms
killpnpm size             # show .codex, pnpm store, and pnpm cache sizes
killpnpm size --codex     # show only home/repo .codex footprint
killpnpm size --pnpm      # show only pnpm store/cache/library paths
killpnpm doctor           # process + agent + disk overview
killpnpm agents           # active pnpm work grouped by launcher
killpnpm clean --plan     # build a cleanup plan; deletes nothing
killpnpm help clean       # command-specific help
killpnpm man              # built-in manual text
killpnpm doctor --json    # machine-readable diagnostics for agents

Diagnostics

killpnpm size is read-only. It reports:

• home and current-repo .codex folders
• detected pnpm store path
• common pnpm store/cache/library locations on macOS and Linux
• traversal limits, skipped symlinks, and truncated measurements

Useful filters:

killpnpm size --codex
killpnpm size --pnpm-store
killpnpm size --pnpm-cache
killpnpm size --library
killpnpm size --max-depth 8 --max-files 20000

killpnpm doctor combines active pnpm process groups with disk diagnostics. It is the fastest way to answer: what is running, who launched it, what would be killed, and where the local pnpm/Codex weight is sitting.

Cleanup Planning

killpnpm clean --plan builds a guarded cleanup plan from the same diagnostic paths. It does not delete files.

killpnpm clean --plan
killpnpm clean --plan --pnpm-cache
killpnpm clean --plan --target ~/Library/Caches/pnpm
killpnpm clean --plan --json

The plan marks targets as recommended, blocked, protected, or manual. Active pnpm process groups block pnpm cleanup recommendations. --execute is intentionally unsupported; use pnpm store prune for store cleanup and inspect broad state folders like ~/.codex manually.

Help And Man

killpnpm --help
killpnpm size --help
killpnpm help doctor
killpnpm man
killpnpm man clean
man killpnpm

The npm package includes a killpnpm(1) man page for systems that install npm package man entries.

Interactive Controls

up/down   move
wheel     scroll the visible command/process table
click     focus a visible row
click ●/○ toggle a row selection marker
x/space   select a row
Enter     kill selected row(s), with confirmation
a         select all visible rows
d/tab     show processes for the selected command
b         back to command list
r         refresh
q         quit

Safety

killpnpm kills process groups, not just one parent process. That is useful for dev servers because children normally stop with the command that launched them.

Interactive kills require confirmation. For automation, use --yes.

Use --tree before killing when you want to inspect every process in the target process group. Use --verify or --force-after <ms> when you need confirmation that the process group actually exited.

The launcher/agent column is inferred by walking the parent process chain. It is best-effort attribution, not a security boundary.

Platform Support

Tested design target:

• macOS
• Linux

Windows is not supported yet because process groups and ps output work differently there.

License

MIT