proc: freeing a port in one command

The problem

When a dev server prints "address already in use" and does not start, you have to find the process that is using the port and stop it. Coding agents do the same work. A Hacker News user said in a comment that Claude ran a command to find and kill processes by a name pattern. The pattern also matched the command, so the command killed itself first. This happened to them several times.

The maker’s README table compares proc with combinations of commands such as lsof and kill for each task. With -i and a port, lsof shows the process that uses that port, and with -t it prints only process IDs. To use the port again, you find the process ID with lsof and pass it to kill. Then you run lsof again to check that nothing uses the port.

How it solves it

proc was posted as a Show HNShow HNA post on Hacker News, a developer community, in which someone presents what they made. Its title starts with "Show HN:". on October 26, 2026. You pick the target by port (:3000), PID, name or file path. proc free :3000 stops the process on that port and then checks that the port is free. proc why :3000 shows the process on the port and its parent processes. When proc finds targets by name, it leaves out its own process and its parent processes, such as the shell that ran it.

With --json, it returns the result as JSON. Every command also returns one of five exit codes. The repository also has an agent skillagent skillA file of instructions that a coding agent reads for a certain task. It says when to use which commands. file that teaches coding agents such as Claude Code and Codex how to use proc.

What is different

The first difference is how you read the result. By default lsof prints a table for people, and -t or -F switch it to a format that other programs can read. With --json, every proc command prints one JSON document, and every document has fields named action and success. It returns exit code 2 when it finds no target and 4 for invalid input. So an agent can decide what to do next from the exit code, without parsing the output. The tradeoff is that proc is one more thing to install, and on Linux it needs the ssssA Linux command that prints network socket information, such as which process uses which port. It ships in the iproute2 package. command for port lookups.

The second difference is how you check before a kill. A command that pipes lsof into kill stops the process as soon as it runs. proc’s --dry-run shows the processes it would stop and stops nothing. When a person runs proc kill or proc free in a terminal, proc asks for confirmation. But with --json, it stops the process without asking, even without --yes. In the skill file for agents, the maker says to always pass --yes to destructive commands. This instruction suggests that proc asks for confirmation without --yes, even with --json.

How it was built

• The repository has 145 commits, from January 8 to October 25, 2026. The v1.0.0 commit on January 12 is titled "The process manager for humans". The JSON error format and the agent skill were added in v1.10.0 on March 24.
• 109 commits have a Co-authored-by trailer for Claude.
• The src directory has 8,264 lines of Rust. The test file tests/cli_json.rs, which checks the JSON output, has 571 lines.

Running it

I cloned the repository and built it from source. I tested it against Python’s http.server on port 3000.

1. Build. cargo build --release took 1 minute 10 seconds. The binary is 2.4 MB.
2. Port lookup. proc on :3000 failed with Port lookups on Linux need ss. This computer had lsof but not ss. The install section of the README does not mention this. Only the changelog has an entry that adds the iproute2 package to the Docker image. That package includes ss. I extracted only ss from the iproute2 package and added it to PATH. The lookup then worked.
3. Tracing the cause. proc why :3000 showed the http.server process and its parent processes as a tree.
4. Preview. proc kill :3000 --dry-run --json printed JSON with 1 process to stop. The server kept running.
5. Errors. A port with nothing on it returned exit code 2. proc returned exit code 4 for an invalid flag, an out-of-range port or an unknown signal name. All errors were printed as JSON. I ran proc kill 'proc kill' --dry-run through bash -c. proc skipped the shell whose command line contained proc kill. It found no target and returned exit code 2.
6. Confirmation. In a terminal, proc free :3000 asked [y/N]. With only --json added, the same command stopped the process without asking. The docs for free say it asks for confirmation unless --yes is given. The ask_confirm function in the code skips the confirmation with --json.
7. Speed. On a 4-core Linux computer, I ran proc on :3000 --json 10 times. The median wall-clock time was 18 ms. lsof -t -i :3000 took 10 ms under the same conditions.

The README’s description of JSON output and exit codes was correct. I did not test exit code 3 (permission denied).

Kill 1 process to free 1 port? [y/N]
{
  "action": "free",
  "success": true,
  "results": [
    {
      "port": 3000,
      "freed": true
    }
  ]
}

Not checked

• macOS and Windows. proc uses lsof for port lookups on macOS. Run the same tests on macOS and Windows.
• The agent skill. Install the agent skill with npx skills add yazeed/proc-cli and check whether Claude Code uses --dry-run first when it stops the process on a port.
• Permission denied (exit code 3). Test it on a process owned by another user.

Verdict

It works. The lookup, preview and stop commands returned JSON and exit codes. But with --json, proc stopped processes without asking. The docs for proc free say it asks for confirmation. It is worth trying if a coding agent often starts and cleans up dev servers. proc is not a good fit if a person must confirm before each kill.