proc

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

Find what's on a port, why it's there, and stop it, in one command you'd guess on the first try. On macOS, Linux and Windows.

brew install yazeed/proc/proc

Also on npm, cargo, Scoop, Nix and Docker.

A dev server won't start because port 3000 is taken. proc finds the old tmux session holding it, frees the port, then cleans up what else was left running.

Docs: commands · install · FAQ · agent skill · changelog

One command instead of a pipeline

Full comparison →

It asks before it changes anything

• Looking is free. on, for, by, in, list, info, ports, tree, why, stuck and orphans only read.
• Changing asks first. kill, stop, freeze, thaw, free, unstick, orphans --kill and stuck --kill show what they will touch and wait for a yes. --dry-run shows the list and does nothing else; --yes skips the question.
• --json is not a yes. A script or agent that runs a changing command with --json and no --yes gets exit 4, nothing changed, and the list of processes it would have touched. The same goes for running without a terminal.
• A name means the whole name. proc kill node stops processes named node and leaves Claude Helper alone. Add --cmd for the looser, pkill -f style match.
• A name is a search, not an approval. Preview a name with --dry-run, and use --yes only with a :port or a PID you have seen.

proc kill node --in . --dry-run   # what would stop, in this project only
proc kill :3000                   # asks first
proc free :3000 --yes             # a port target: no question

Install

--pid=host lets proc in Docker see the host's processes, and --net=host its ports (for on :port, ports and free).

Check it works:

proc --version
proc ports

The AUR package is not published by this project and can lag behind releases. Check proc --version after installing: before 2.0, a name matched any part of a command line and --json counted as --yes.

Manual download:

# macOS (Apple Silicon)
curl -fsSL https://github.com/yazeed/proc-cli/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-cli/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-cli/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-cli/releases/latest/download/proc-linux-aarch64.tar.gz | tar xz
sudo mv proc-linux-aarch64 /usr/local/bin/proc

# Windows (PowerShell, run as administrator to write to System32)
Invoke-WebRequest -Uri https://github.com/yazeed/proc-cli/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

Nineteen commands, three jobs

Every command takes the same targets, and almost all take --in to stay inside one project, --json for scripts, and --dry-run before anything changes (the changing ones).

Find out

Read-only. Nothing is touched.

Change it

Asks first, or previews with --dry-run.

Keep watching

proc on :3000                   # what's on port 3000?
proc by node --in . --min-cpu 5 # node in this directory using >5% CPU
proc info :3000 1234            # info for a port and a PID
proc tree --min-cpu 5           # process tree, busy processes only
proc watch node -n 1            # node processes, refreshed every second
proc wait :3000 --timeout 60    # wait up to 60s for the process on port 3000 to exit
proc stop worker --signal INT   # ask with SIGINT; force-killed after --timeout
proc orphans --in .             # leftovers from this project

Targets

All commands accept the same targets:

A process named twice is handled once, except by the read-only on and why, which answer each target under its own header. Comma-separated targets (:3000,:8080,node) still work but are deprecated and will be removed in a future major release: a command that gets one prints a note: on stderr with the separate-argument form (human output only; --json is unchanged).

Names. A name matches the whole process name, ignoring case, the way killall and pkill -x read it. proc kill node stops the processes named node and leaves Claude Helper alone, and --by follows the same rule. The file name of the executable and of the first argument count as names too, so a long name that Linux cuts to 15 characters still matches, and on Windows a trailing .exe is optional. Add --cmd to match any part of the name or the full command line instead, like pkill -f: proc kill serve --cmd. A path is not a name: proc kill ./server finds nothing, so use --cmd, or proc for <file> for an executable. proc doesn't expand wildcards; an unquoted node* is expanded by your shell into file names, so use --cmd for partial matches.

--in. --in (short -i) takes the next word as its directory unless that word starts with -; a bare --in is the current directory. Put it after the targets (proc kill 1234 5678 --in .) or write --in=DIR.

Filters

Not every filter is on every command. --in, --by (short -b) and --cmd work on nearly all of them, including the ones that change processes. The rest narrow what the finding commands show:

Options

For scripts and coding agents

Every process and port command prints JSON with --json: one document per command, with action (the command name) and success. proc watch --json streams one per refresh. Exit codes always mean the same thing.

proc on :8080 --json | jq '.process | {pid, cwd, uptime_secs}'

• Errors are JSON too, including invalid flags: {"action", "success": false, "error", "exit_code"}. "success": false always comes with a non-zero exit code.
• Exit 4 means nothing was done, and the error adds "reason": "invalid_input" (a wrong flag, value or argument), "needs_confirmation" or "not_supported" (this OS cannot do it).
• Preview, then confirm. A command that changes processes, run with --json but without --yes, exits 4 with "needs_confirmation": true and "processes" (the ones it would have changed), so a script can show them before running it again with --yes.
• not_found lists the targets that matched nothing (empty when all were found). It is in the JSON of on, why, info, kill, stop, freeze, thaw, unstick, free and wait, and in the exit 4 output above. list and watch do not have it.
• A prompt shows what you would approve. The list of processes goes to the terminal beside the [y/N] question: on stdout, or on stderr when stdout is a file or a pipe. If the list cannot be shown, nothing is asked and nothing is changed (exit 4).
• A reader that stops early ends proc quietly. proc list | head -n1 exits 0 without an error, and proc kill 1234 --yes | head -n1 still kills the process and exits with the code of the kill (0 if it worked, 2 if there was nothing to kill): a closed pipe never changes the result, on stdout or stderr. A write that fails for another reason (a full disk) is exit 1, with one line on stderr.

Full schemas: skills/proc-cli/reference.md.

Agent skill

Teach your coding agent (Claude Code, Codex, Cursor, Gemini CLI and others) when to reach for proc and how to use it safely, with structured JSON output:

npx skills add yazeed/proc-cli

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

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

The skill lives in skills/proc-cli/ and follows the Agent Skills standard. What it teaches, how to update it, and prompts to try →

Platform support

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.

proc is for processes and ports on the machine it runs on. It is not for containers, system services or remote hosts (see PHILOSOPHY.md).

Shell completions and man page

# 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

# Elvish and PowerShell: proc completions elvish, proc completions powershell

# 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-cli
cd proc-cli
cargo build --release

The binary will be at target/release/proc.

Use as a library

proc is also a Rust crate, proc_cli: see the API docs on docs.rs and the Library API entries in the changelog.

Contributing

See CONTRIBUTING.md. The principles behind the commands are in PHILOSOPHY.md.

License

MIT