process_check

A terminal-based process monitor CLI for your PC — a lightweight, scriptable alternative to htop, built with Node.js.

View running processes, sort and filter them, watch a live auto-refreshing dashboard, get alerted when CPU/memory thresholds are crossed, and kill processes — all from the command line.

Features

• Snapshot view — list currently running processes with PID, name, user, state, CPU%, and memory%
• Live dashboard mode — auto-refreshing view (like top/htop) with a system summary header (CPU load, memory usage, process count)
• Sorting — sort by CPU usage, memory usage, or PID
• Filtering — show only processes matching a name
• Limit — control how many processes are displayed
• Kill processes — terminate a process by PID, with a confirmation prompt (or force-kill without prompting)
• Threshold alerts — flag any process that crosses a CPU% or memory% limit you set, with a visual warning badge and a terminal bell sound the moment a process crosses the line
• Color-coded output — CPU usage is color-coded (green/yellow/red) for quick scanning

Requirements

• Node.js v18 or later
• npm (comes bundled with Node.js)

Installation

Install globally from npm:

npm install -g process_check

This installs the procmon command globally, so you can run it from any folder on your system.

Usage

Once installed globally, use the procmon command followed by a subcommand.

procmon <command> [options]

Commands

| Command | Description | |---|---| | list | Show a one-time snapshot of running processes | | watch | Live auto-refreshing dashboard | | kill <pid> | Kill a process by its PID |

list — snapshot view

procmon list

Options:

| Flag | Description | Default | |---|---|---| | -s, --sort <type> | Sort by cpu, mem, or pid | cpu | | -n, --limit <number> | Number of processes to show | 30 | | -f, --filter <name> | Show only processes whose name matches | — | | --cpu-threshold <percent> | Flag processes above this CPU% | — | | --mem-threshold <percent> | Flag processes above this MEM% | — |

Examples:

procmon list
procmon list --sort mem --limit 10
procmon list --filter chrome
procmon list --cpu-threshold 50 --mem-threshold 20

watch — live dashboard

procmon watch

Same options as list, plus:

| Flag | Description | Default | |---|---|---| | -i, --interval <ms> | Refresh interval in milliseconds | 2000 |

The dashboard auto-refreshes at the given interval, showing a live system summary (CPU load, memory usage, process count, current time) followed by the process table. Press Ctrl+C to exit.

If --cpu-threshold or --mem-threshold is set, any process that newly crosses the limit triggers a terminal bell and an ALERT line — it only beeps once per crossing, not on every refresh, so it won't spam you while a process stays over the limit.

Examples:

procmon watch
procmon watch --interval 3000
procmon watch --sort mem --cpu-threshold 20 --mem-threshold 5
procmon watch --filter node --interval 5000

kill — terminate a process

procmon kill <pid>

Looks up the process, shows its name and user, and asks for confirmation before sending SIGTERM.

| Flag | Description | |---|---| | --force | Skip the confirmation prompt and send SIGKILL instead of SIGTERM |

Examples:

procmon kill 1234
procmon kill 1234 --force

⚠️ Be careful with kill, especially --force — it will terminate the process without further warning once confirmed.

Example output

CPU 15.7%  |  Mem 0.33GB / 3.90GB  |  Processes: 5  |  9:07:41 AM

PID     NAME                     USER           STATE       CPU%    MEM%
1234    chrome                   nikhil         running     12.3    4.20
5678    node                     nikhil         running     8.1     1.15
9012    explorer                 nikhil         running     2.4     0.90

Notes

• CPU% readings can appear as 0 on the very first render in watch mode — this is expected, since the underlying system library needs one interval to establish a baseline before it can compute usage accurately.
• kill/--force behavior is subject to your OS's permission model — you may not be able to kill processes owned by other users or system processes without elevated privileges.

License

ISC