proc

Semantic CLI tool for process management. Target by port, process id (PID), name or path.

proc on :3000                   # what's on port 3000?
proc for ./script.py            # what's running this file?
proc by node --in . --min-cpu 5 # node in cwd using >5% CPU
proc kill :3000,:8080,node      # kill mixed targets at once
proc info :3000,1234            # info for port + PID

Why proc?

Task	proc	Without proc
What's on port 3000?	proc on :3000	lsof -i :3000 -P -n
Kill it	proc kill :3000	lsof -i :3000 -t | xargs kill -9
Free port 3000	proc free :3000	lsof -i :3000 -t | xargs kill && sleep 1 && lsof -i :3000
Why is port busy?	proc why :3000	lsof -i :3000 + ps -o ppid= chain
Pause a process	proc freeze node	kill -STOP $(pgrep node)
Find orphans	proc orphans --in .	No standard tool
Wait for process	proc wait node	while ps aux | grep node | grep -v grep; do sleep 5; done
Ports used by node	proc on node	lsof -i -P -n | grep node
Node processes in cwd	proc by node --in .	ps aux | grep node + manual check
Kill mixed targets	proc kill :3000,:8080,node	Three separate commands
Watch in real-time	proc watch node	watch -n2 'ps aux | grep node'
What runs this file?	proc for ./app.js	lsof ./app.js or fuser ./app.js

One syntax. One tool. Full comparison →

Install

Platform	Command
macOS	brew install yazeed/proc/proc
Windows	scoop bucket add proc https://github.com/yazeed/scoop-bucket-proc && scoop install proc
Rust	cargo install proc-cli
npm/bun	npm install -g proc-cli
Nix	nix profile install github:yazeed/proc
Docker	docker run --rm -it --pid=host --net=host yazeed/proc
Shell	curl -fsSL https://raw.githubusercontent.com/yazeed/proc/main/install.sh | bash

More options

Platform	Method	Command
macOS/Linux	cargo-binstall	cargo binstall proc-cli
Arch Linux	AUR	yay -S proc (pending)

Manual download:

# macOS (Apple Silicon)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-darwin-aarch64.tar.gz | tar xz
sudo mv proc-darwin-aarch64 /usr/local/bin/proc

# macOS (Intel)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-darwin-x86_64.tar.gz | tar xz
sudo mv proc-darwin-x86_64 /usr/local/bin/proc

# Linux (x86_64)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-linux-x86_64.tar.gz | tar xz
sudo mv proc-linux-x86_64 /usr/local/bin/proc

# Linux (ARM64)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-linux-aarch64.tar.gz | tar xz
sudo mv proc-linux-aarch64 /usr/local/bin/proc

# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/yazeed/proc/releases/latest/download/proc-windows-x86_64.exe.zip -OutFile proc.zip
Expand-Archive proc.zip -DestinationPath .
Move-Item proc-windows-x86_64.exe C:\Windows\System32\proc.exe

Agent Skill

Teach your coding agent (Claude Code, Codex, Cursor, Gemini CLI and others) to use proc with structured JSON output:

npx skills add yazeed/proc

In Claude Code you can also install it as a plugin:

/plugin marketplace add yazeed/proc
/plugin install proc-cli@proc-cli

The skill lives in skills/proc-cli/ and follows the Agent Skills standard.

Quick Start

What's using port 3000?

proc on :3000

Kill it:

proc kill :3000

What's running this script?

proc for ./script.py

Find all node processes in current directory using >5% CPU:

proc by node --in . --min-cpu 5

Kill multiple targets at once:

proc kill :3000,:8080,node

Watch processes in real-time:

proc watch node --in .

Target Syntax

All commands accept the same target syntax:

Target	Example	Description
Port	:3000	Process listening on port 3000
PID	1234	Process with ID 1234
Name	node	All processes named "node"
Multi	:3000,:8080,node	Comma-separated targets

Commands

Discovery

Command	Alias	Description
on <target>	:	Bidirectional port/process lookup
for <file>	f	Find processes by file path
by <name>	b	Filter processes by name
in <path>		Filter processes by working directory
list	l, ps	List all processes
info <target>	i, inspect	Detailed process information
ports	p	List all listening ports
tree	t	Process hierarchy
watch	w, top	Real-time process monitoring
why <target>		Trace process ancestry (why is this port busy?)
orphans	o	Find orphaned processes
stuck	x	Find hung processes

Lifecycle

Command	Alias	Description
kill <target>	k	Force kill (SIGKILL)
stop <target>	s	Graceful stop (SIGTERM, --signal for custom)
freeze <target>		Pause process (SIGSTOP)
thaw <target>		Resume frozen process (SIGCONT)
free <:port>		Kill process and verify port freed
wait <target>		Block until process(es) exit
unstick	u	Recover stuck processes

Filters

Filters can be combined with discovery and lifecycle commands:

Filter	Description
--in <path>	Filter by working directory
--by <name>	Filter by process name
--path <path>	Filter by executable path (list)
--min-cpu <n>	Processes using >n% CPU
--min-mem <n>	Processes using >n MB memory
--min-uptime <s>	Processes running longer than s seconds
--parent <pid>	Children of a specific parent PID
--status <s>	Filter by status: running, sleeping, stopped, zombie
--exposed	Only network-exposed ports (ports)
--local	Only localhost ports (ports)
--range <s-e>	Filter ports by range (e.g., 3000-9000)
--sort/-s <key>	Sort by: cpu, mem, pid, name
--limit/-n <n>	Limit number of results
--ancestors/-a	Show ancestry path to root (tree)
--depth/-d <n>	Maximum tree depth (default: 10)
--compact/-C	Show PIDs only in compact view (tree)
--timeout/-t <s>	Seconds before considered stuck (default: 300)

Options

Option	Short	Description
--json	-j	JSON output
--verbose	-v	Show paths, cwd, full commands
--yes	-y	Skip confirmation
--dry-run		Preview without executing
--force	-f	Force termination if recovery fails (unstick)
--graceful	-g	Send SIGTERM instead of SIGKILL (kill)
--signal	-S	Custom signal: HUP, INT, USR1, etc. (stop)
--kill	-k	Kill found processes (stuck, orphans)
--wait		Max seconds to wait for port to free (free)
--interval	-n	Poll/refresh interval in seconds (wait, watch)
--timeout	-t	Max seconds to wait before giving up (wait, stop)
--quiet	-q	Suppress periodic status messages (wait)

Scripting

With --json, every command prints one JSON document with action (the command name) and success. proc watch --json streams one per refresh. Errors, including invalid flags, are JSON too: {"action", "success": false, "error", "exit_code"}.

Exit code	Meaning
0	Success
1	Error, or not fully successful: a process failed, a port stayed busy, wait timed out
2	Process or port not found
3	Permission denied
4	Invalid input (unknown flag, bad argument, invalid signal)

"success": false always comes with a non-zero exit code. Full schemas: skills/proc-cli/reference.md.

Examples

# What's on port 3000?
proc on :3000

# What ports is node using?
proc on node

# What's running this file?
proc for ./script.py

# What has this file open?
proc for /var/log/app.log

# Node processes in current directory
proc by node --in .

# Processes using >10% CPU
proc list --min-cpu 10

# Kill everything on ports 3000 and 8080
proc kill :3000,:8080

# Kill only node processes in current directory
proc kill node --in . --dry-run

# Process tree filtered by CPU usage
proc tree --min-cpu 5

# Watch all processes sorted by CPU (alias: proc top)
proc watch

# Watch node processes with 1s refresh
proc watch node -n 1

# Watch process on port 3000
proc watch :3000

# Watch processes in cwd sorted by memory
proc watch --in . --sort mem

# Freeze/thaw (pause and resume)
proc freeze node               # Pause all node processes
proc thaw node                 # Resume them

# Free a port (kill + verify available)
proc free :3000                # Kill and confirm port 3000 is free
proc free :3000,:8080 --yes    # Free multiple ports

# Why is port 3000 busy?
proc why :3000                 # Show ancestry chain with port context

# Find orphaned processes
proc orphans                   # List orphans
proc orphans --in . --kill     # Kill orphans in current directory

# Wait for processes to exit
proc wait node                 # Block until all node processes exit
proc wait :3000 --timeout 60   # Wait up to 60s for port process to exit
proc wait node -n 10 -q        # Check every 10s, quiet mode

# Send custom signal
proc stop nginx --signal HUP   # Reload config (SIGHUP)

# Find and recover stuck processes
proc stuck
proc unstick --force

Platform Support

Platform	Architecture	Status
macOS	Apple Silicon (ARM64)	✅
macOS	Intel (x86_64)	✅
Linux	x86_64	✅
Linux	ARM64	✅
Windows	x86_64	✅
Docker	linux/amd64, linux/arm64	✅

The Linux binaries are statically linked (musl) and need no particular glibc version, so they also run on Alpine and on older releases such as Debian 10, Ubuntu 20.04 and Amazon Linux 2.

Shell Completions

Generate completions for your shell:

# Bash
proc completions bash > /etc/bash_completion.d/proc

# Zsh
proc completions zsh > ~/.zsh/completions/_proc

# Fish
proc completions fish > ~/.config/fish/completions/proc.fish

Man Page

Generate and install the man page:

proc manpage | sudo tee /usr/local/share/man/man1/proc.1 > /dev/null

Building from Source

git clone https://github.com/yazeed/proc
cd proc
cargo build --release

The binary will be at target/release/proc.

Contributing

See CONTRIBUTING.md.

License

MIT