docs
Teach your coding agent to use proc: install the proc-cli skill for Claude Code, Codex, Cursor, Gemini CLI and others.
Install
npx skills add https://github.com/yazeed/proc-cli/tree/main/docs
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install yazeed-proc-cli@llmmart
git clone https://github.com/yazeed/proc-cli.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole yazeed/proc-cli collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
The proc-cli skill teaches coding agents (Claude Code, Codex, Cursor, Gemini CLI and others) when to reach for proc and how to use it safely. Instead of lsof -ti :3000 | xargs kill -9, your agent previews with proc free :3000 --dry-run, reads structured JSON, and checks with you before touching a process it didn't start. It adds --yes only for a process it started itself or after you've seen the list and agreed, and never with a name. proc enforces its side too: nothing that stops, kills or pauses a process runs without --yes unless a person confirms at the prompt, --json never counts as a yes, and a name matches only the whole process name.
Install
proc itself has to be installed first (see install). Then add the skill:
npx skills add yazeed/proc-cli
Or with bun:
bunx skills add yazeed/proc-cli
To pick the agent and where it's installed:
npx skills add yazeed/proc-cli --skill proc-cli -a claude-code -y # one agent, this project
npx skills add yazeed/proc-cli --skill proc-cli -g # every project (user-level)
Claude Code plugin
In Claude Code, you can install it as a plugin instead:
/plugin marketplace add yazeed/proc-cli
/plugin install proc-cli@proc-cli
Update
npx skills update
Installs always fetch the current skill from the repository, so a new install is up to date too. The skill is written for proc 2.0 or later. It tells your agent to check proc --version, and to ask you to upgrade rather than run destructive commands on an older proc.
What your agent learns
- When to use proc: a busy port (
EADDRINUSE, "address already in use"), what's listening on a port or running in a directory, stopping or freeing something, a dev server that won't start, a stuck process or a slow machine, and cleaning up the servers and browsers it started. Not containers, system services or remote hosts - A safety model on the first screen: which commands only read, which can be undone (
freeze,thaw), and which end a process (stop,kill,free); a process is its own only if it started it and recorded the PID; a name is a search, not approval - The contract:
--jsonon every command, one JSON document per command (watchstreams one per refresh), and fixed exit codes (0 success, 1 error, 2 not found, 3 permission denied, 4 invalid input or confirmation needed). Every error says why inreason, and the agent branches on it, never on the text; exit 4 means nothing changed (invalid_input,needs_confirmationornot_supported); withneeds_confirmationit shows you the list, and it doesn't retry with--yeson its own - Playbooks: a busy port, stopping its own servers by PID with a guard (
--start-time,--inand--by), stopping something it didn't start only after you approve the PIDs, cleaning up only what it recorded, and readingstuckandorphansas leads rather than verdicts - Safety: preview with
--dry-run, show you the PID, name, directory, command and parent, and wait for a yes; preferstopoverkill; never--killonorphansorstuck; ask beforesudo - Gotchas:
killandstopdon't signal child processes,:3000is a port but3000is a PID, a port can have several holders,--innarrows a search but doesn't prove a process is the agent's, and an orphaned process isn't necessarily abandoned
Try it
Once it's installed, ask your agent things like:
- "What's on port 3000?"
- "Port 3000 is taken, free it"
- "Why is port 8080 busy?"
- "What did you leave running in this project?"
- "My machine is slow, what's using the CPU?"
- "Wait for the build to finish, then start the server"
Where it lives
- Source:
skills/proc-cli/in the repository (SKILL.md, andreference.mdfor every JSON output) - Listing: skills.sh/yazeed/proc-cli/proc-cli, where it passes the security audits from Gen Agent Trust Hub, Socket and Snyk
- Evals:
evals.mdlists the tasks the skill is checked against, each with what the agent must and must never do - Format: the Agent Skills standard, so any agent that supports skills can use it
Files (proc-cli)
-
assets
-
css
-
style.css 22.7 KB · in bundle
-
-
js
-
site.js 8.3 KB
Loading…
-
-
demo.mp4 377.2 KB · in bundle
-
social-card.png 45.3 KB · in bundle
-
-
commands
-
by.md 2.4 KB
Loading… -
for.md 2.3 KB
Loading… -
free.md 1.5 KB
Loading… -
freeze.md 1.9 KB
Loading… -
in.md 2.2 KB
Loading… -
index.md 4.7 KB
Loading… -
info.md 3.1 KB
Loading… -
kill.md 2.9 KB
Loading… -
list.md 3.2 KB
Loading… -
on.md 4.2 KB
Loading… -
orphans.md 1.8 KB
Loading… -
ports.md 1.4 KB
Loading… -
stop.md 2.3 KB
Loading… -
stuck.md 2 KB
Loading… -
thaw.md 1.7 KB
Loading… -
tree.md 2.2 KB
Loading… -
unstick.md 1.9 KB
Loading… -
wait.md 2.5 KB
Loading… -
watch.md 3.2 KB
Loading… -
why.md 1.7 KB
Loading…
-
-
_data
-
faq.yml 7 KB
Loading… -
reader.yml 11.1 KB
Loading… -
release.yml 140 B
Loading…
-
-
_includes
-
changelog-nav.html 1.5 KB · in bundle
-
commands-nav.html 823 B · in bundle
-
reader-chips.html 492 B · in bundle
-
reader-explain.html 190 B · in bundle
-
schema.html 2.3 KB · in bundle
-
-
_layouts
-
default.html 3.8 KB · in bundle
-
page.html 676 B · in bundle
-
post.html 1.1 KB · in bundle
-
-
_posts
-
2026-01-15-why-i-built-proc.md 4.4 KB
Loading… -
2026-03-06-automating-process-management-shell-scripts.md 14 KB
Loading… -
2026-03-06-find-kill-process-on-port-macos-linux.md 14.5 KB
Loading… -
2026-03-06-proc-vs-lsof-fuser-killport-fkill.md 7.1 KB
Loading… -
2026-03-06-ps-grep-awk-kill-pipeline-explained.md 9.3 KB
Loading… -
2026-03-06-ss-vs-netstat-vs-lsof.md 12.2 KB
Loading… -
2026-03-06-zombie-orphan-stuck-processes-guide.md 13.6 KB
Loading… -
2026-03-10-eaddrinuse-address-already-in-use-fix.md 5.4 KB
Loading… -
2026-03-10-kill-vs-pkill-vs-killall.md 6 KB
Loading… -
2026-03-10-nodejs-child-process-management.md 7.6 KB
Loading… -
2026-03-10-nohup-vs-disown-vs-background.md 6.4 KB
Loading… -
2026-03-10-unix-signals-complete-reference.md 9.3 KB
Loading… -
2026-10-25-whats-new-in-proc.md 5 KB
Loading… -
2026-10-31-whats-new-in-proc-2.md 5.6 KB
Loading…
-
-
apple-touch-icon.png 3.8 KB · in bundle
-
apt.md 1.4 KB
Loading… -
changelog.md 68.7 KB
Loading… -
CNAME 12 B · in bundle
-
faq.md 606 B
Loading… -
favicon.ico 4.1 KB · in bundle
-
favicon.svg 369 B · in bundle
-
index.html 10.3 KB · in bundle
-
install.md 4.1 KB
Loading… -
posts.html 767 B · in bundle
-
skill.md 4.6 KB
--- layout: page title: Agent skill description: "Teach your coding agent to use proc: install the proc-cli skill for Claude Code, Codex, Cursor, Gemini CLI and others." permalink: /skill --- The proc-cli skill teaches coding agents (Claude Code, Codex, Cursor, Gemini CLI and others) when to reach for proc and how to use it safely. Instead of `lsof -ti :3000 | xargs kill -9`, your agent previews with `proc free :3000 --dry-run`, reads structured JSON, and checks with you before touching a process it didn't start. It adds `--yes` only for a process it started itself or after you've seen the list and agreed, and never with a name. proc enforces its side too: nothing that stops, kills or pauses a process runs without `--yes` unless a person confirms at the prompt, `--json` never counts as a yes, and a name matches only the whole process name. ## Install proc itself has to be installed first (see [install](install)). Then add the skill: ```bash npx skills add yazeed/proc-cli ``` Or with bun: ```bash bunx skills add yazeed/proc-cli ``` To pick the agent and where it's installed: ```bash npx skills add yazeed/proc-cli --skill proc-cli -a claude-code -y # one agent, this project npx skills add yazeed/proc-cli --skill proc-cli -g # every project (user-level) ``` ### Claude Code plugin In Claude Code, you can install it as a plugin instead: ```text /plugin marketplace add yazeed/proc-cli /plugin install proc-cli@proc-cli ``` ## Update ```bash npx skills update ``` Installs always fetch the current skill from the repository, so a new install is up to date too. The skill is written for proc 2.0 or later. It tells your agent to check `proc --version`, and to ask you to upgrade rather than run destructive commands on an older proc. ## What your agent learns - **When to use proc**: a busy port (`EADDRINUSE`, "address already in use"), what's listening on a port or running in a directory, stopping or freeing something, a dev server that won't start, a stuck process or a slow machine, and cleaning up the servers and browsers it started. Not containers, system services or remote hosts - **A safety model on the first screen**: which commands only read, which can be undone (`freeze`, `thaw`), and which end a process (`stop`, `kill`, `free`); a process is its own only if it started it and recorded the PID; a name is a search, not approval - **The contract**: `--json` on every command, one JSON document per command (`watch` streams one per refresh), and fixed exit codes (0 success, 1 error, 2 not found, 3 permission denied, 4 invalid input or confirmation needed). Every error says why in `reason`, and the agent branches on it, never on the text; exit 4 means nothing changed (`invalid_input`, `needs_confirmation` or `not_supported`); with `needs_confirmation` it shows you the list, and it doesn't retry with `--yes` on its own - **Playbooks**: a busy port, stopping its own servers by PID with a guard (`--start-time`, `--in` and `--by`), stopping something it didn't start only after you approve the PIDs, cleaning up only what it recorded, and reading `stuck` and `orphans` as leads rather than verdicts - **Safety**: preview with `--dry-run`, show you the PID, name, directory, command and parent, and wait for a yes; prefer `stop` over `kill`; never `--kill` on `orphans` or `stuck`; ask before `sudo` - **Gotchas**: `kill` and `stop` don't signal child processes, `:3000` is a port but `3000` is a PID, a port can have several holders, `--in` narrows a search but doesn't prove a process is the agent's, and an orphaned process isn't necessarily abandoned ## Try it Once it's installed, ask your agent things like: - "What's on port 3000?" - "Port 3000 is taken, free it" - "Why is port 8080 busy?" - "What did you leave running in this project?" - "My machine is slow, what's using the CPU?" - "Wait for the build to finish, then start the server" ## Where it lives - Source: [`skills/proc-cli/`](https://github.com/yazeed/proc-cli/tree/main/skills/proc-cli) in the repository ([`SKILL.md`](https://github.com/yazeed/proc-cli/blob/main/skills/proc-cli/SKILL.md), and [`reference.md`](https://github.com/yazeed/proc-cli/blob/main/skills/proc-cli/reference.md) for every JSON output) - Listing: [skills.sh/yazeed/proc-cli/proc-cli](https://www.skills.sh/yazeed/proc-cli/proc-cli), where it passes the security audits from Gen Agent Trust Hub, Socket and Snyk - Evals: [`evals.md`](https://github.com/yazeed/proc-cli/blob/main/skills/proc-cli/evals.md) lists the tasks the skill is checked against, each with what the agent must and must never do - Format: the [Agent Skills](https://agentskills.io) standard, so any agent that supports skills can use it -
_config.yml 836 B
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.