yazeed/proc repository overview

⁠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, Windows, FreeBSD and NetBSD.

brew install yazeed/proc/proc

Also on Scoop, apt, dnf, npm, PyPI, cargo, Nix, Docker, and as .deb and .rpm files⁠.

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

Every channel, with who maintains it and how it updates, is on proc-cli.com/install⁠. --pid=host lets proc in Docker see the host's processes, --net=host its ports (for on :port, ports and free), and --cap-add SYS_PTRACE --security-opt apparmor=unconfined which process holds a port or a file when that process isn't root's (Docker drops that capability, and on hosts with AppArmor, such as Ubuntu, its default profile blocks those reads too).

The .deb and .rpm files install proc, its man page and its bash, zsh and fish completions. A file does not update with apt upgrade or dnf upgrade; the apt repository and COPR do.

Check it works:

proc --version
proc ports

# 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

# FreeBSD (x86_64); for NetBSD the file is proc-netbsd-x86_64
curl -fsSL https://github.com/yazeed/proc-cli/releases/latest/download/proc-freebsd-x86_64.tar.gz | tar xz
sudo mv proc-freebsd-x86_64 /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 on 1234                    # what is PID 1234, and what ports is it using?
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.

The process card. on (by port, PID or name), info, for with one hit and why print the same card for a process: Process:, Command:, Directory:, Path:, User:, Parent:, Status:, Resources:, Started:, Children:, then Listening: (every port, with its exposure) and Connections: for a process that listens. proc on 1234 is the card for a PID, proc on :3000 the card for each holder of a port.

Tables. list, by, in, for (several hits), orphans, stuck, watch and the list in front of every --dry-run or question print one table: PID NAME USER CPU% MEM UPTIME COMMAND. A value proc cannot read is -. COMMAND takes the width the other columns leave and ends with … where it is cut; the list you approve prints it whole. With --in, the directory is the second column. --verbose keeps the table, adds PPID STATUS DIR and cuts nothing.

Ports. ports prints PORT PROTO ADDRESS EXPOSURE PID NAME UPTIME COMMAND (EXPOSURE is local or exposed), so each row says what the listener is. --verbose adds USER MEM and the executable's path (PATH) and cuts nothing; --json also gives command, user, uptime_secs and memory_mb per port, and with -v the connection counts.

⁠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", "reason"}. "success": false always comes with a non-zero exit code.
• Every error says why in "reason", one fixed word to branch on: "system_error" (exit 1); "not_found", "command_line_only" (the name is only in command lines; --cmd matches) or "ruled_out" (a guard ruled the process out, listed in "ruled_out_by", or every match was a process proc runs under, listed in "left_out") for exit 2; "permission_denied" (exit 3); and, for exit 4, where nothing was done, "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. With --yes, the receipt lists the same processes as "processes", in the same order, each with an "outcome" ("succeeded" or "failed", and "error" when it failed) and a "count".
• 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. On Linux proc reads processes, ports and open files from /proc, so it needs nothing else installed. The Docker image is the same binary on distroless, with no shell; COPY --from=yazeed/proc-cli /usr/local/bin/proc /usr/local/bin/proc adds it to an image of your own.

On FreeBSD and NetBSD proc reads ports with sockstat and open files with fstat, both in the base system, so it needs nothing installed. The kernel forgets the path of a working directory once the directory is deleted, so proc in a deleted directory exits 4 there, where Linux and macOS still find the processes in it.

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

The Nix package and the .deb and .rpm files install both. With any other install method, add them yourself:

# 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⁠.

⁠Star History

⁠License

MIT