proc: 포트 점유 프로세스를 한 명령으로 종료

무엇이 문제인가

개발 서버가 "address already in use" 오류를 출력하고 시작되지 않으면, 같은 포트를 사용하는 프로세스를 찾아 종료해야 한다. 코딩 에이전트도 같은 일을 한다. Hacker News 의 한 사용자는 댓글에서, Claude 가 이름 패턴으로 프로세스를 찾아 종료하는 명령을 실행하면 그 명령도 같은 패턴과 일치해 대상보다 먼저 종료되는 일이 여러 번 있었다고 했다.

proc 의 제작자는 README 에서 작업마다 proc 명령과 lsof, kill 같은 명령의 조합을 표로 비교했다. lsof 에 -i 로 포트를 지정하면 그 포트를 사용하는 프로세스 목록이 출력되고, -t 를 붙이면 프로세스 ID 만 출력된다. 그래서 포트를 다시 사용하려면 lsof 로 프로세스 ID 를 찾아 kill 에 넘기고, 다시 lsof 로 그 포트를 사용하는 프로세스가 없는지 확인해야 한다.

어떻게 해결했나

proc 은 2026년 10월 26일 Hacker News 에 Show HNShow HN개발자 커뮤니티 Hacker News 에서 자신이 만든 프로덕트를 소개하는 글. 제목이 "Show HN:"으로 시작한다. 글로 올라왔다. proc 은 찾기, 종료, 확인을 명령 하나로 묶는다. 대상은 포트(:3000), PID, 이름, 파일 경로로 지정한다. proc free :3000 은 그 포트의 프로세스를 종료한 뒤 그 포트를 사용하는 프로세스가 없는지 확인한다. proc why :3000 은 그 프로세스를 실행한 부모 프로세스들을 차례로 보여 준다. 이름으로 프로세스를 찾을 때는 proc 자신과 proc 을 실행한 셸 같은 상위 프로세스를 대상에서 제외한다.

--json 을 붙이면 결과를 JSON 으로 출력한다. 종료 코드는 다섯 가지로 구분한다. 저장소에는 Claude Code, Codex 같은 코딩 에이전트에게 proc 사용법을 알려 주는 에이전트 스킬에이전트 스킬코딩 에이전트가 특정 작업을 할 때 읽도록 만든 지침 파일. 언제 어떤 명령을 쓸지 작성해 둔다. 파일도 있다.

무엇이 다른가

첫째, 결과를 읽는 방법이 다르다. lsof 의 기본 출력은 눈으로 읽기 위한 표이고, -t 나 -F 를 붙이면 다른 프로그램이 읽기 쉬운 형식으로 바뀐다. proc 은 --json 을 붙이면 모든 명령이 JSON 문서 하나를 출력한다. 명령과 관계없이 문서에는 action 과 success 필드가 있다. 대상을 찾지 못하면 종료 코드 2, 잘못된 입력이면 4 를 반환하므로, 에이전트는 출력을 파싱하지 않고 종료 코드로 다음 행동을 결정할 수 있다. 트레이드오프는 proc 을 따로 설치해야 하고, 리눅스에서는 포트를 조회하는 데 ssss리눅스에서 네트워크 소켓 정보를 출력하는 명령. 어떤 포트를 어떤 프로세스가 사용하는지 확인할 때 쓴다. iproute2 패키지에 들어 있다. 명령이 필요하다는 점이다.

둘째, 종료 전에 확인하는 방법이 다르다. lsof 의 결과를 kill 에 넘기는 명령은 실행하는 즉시 프로세스를 종료한다. proc 의 --dry-run 은 종료할 프로세스를 보여 주고 아무것도 종료하지 않는다. 사용자가 터미널에서 proc kill 이나 proc free 를 실행하면 proc 은 프로세스를 종료하기 전에 확인을 요청한다. 다만 --json 을 붙이면 --yes 가 없어도 확인 없이 종료한다. 제작자는 에이전트 스킬 파일에서 파괴적인 명령에는 항상 --yes 를 붙이라고 안내한다. 이 안내만 보면 --json 을 붙여도 --yes 가 없을 때는 확인을 요청할 것처럼 읽힌다.

어떻게 만들었나

• 커밋 145개는 2026년 1월 8일부터 10월 25일까지 작성됐다. 1월 12일 v1.0.0 커밋의 제목은 "The process manager for humans" 였다. JSON 오류 형식과 에이전트 스킬은 3월 24일 v1.10.0 에 추가됐다.
• 커밋 109개에 Claude 와 함께 작성했다는 Co-authored-by 트레일러가 있다.
• src 디렉토리의 Rust 코드는 8,264줄이다. JSON 출력을 검사하는 테스트 파일 tests/cli_json.rs 는 571줄이다.

실행해 보니

저장소를 클론해 소스로 빌드하고, 포트 3000 에 Python 의 http.server 를 실행해 시험했다.

1. 빌드. cargo build --release 에 1분 10초가 걸렸다. 실행 파일은 2.4 MB 다.
2. 포트 조회. proc on :3000 은 Port lookups on Linux need ss 오류로 실패했다. 시험에 사용한 리눅스 컴퓨터에는 lsof 는 있었지만 ss 는 없었다. README 의 설치 안내에는 ss 가 필요하다는 내용이 없다. 변경 기록에만 Docker 이미지에 ss 를 포함한 iproute2 패키지를 추가했다는 항목이 있다. iproute2 패키지에서 ss 실행 파일만 추출해 PATH 에 추가하자 조회가 성공했다.
3. 원인 추적. proc why :3000 은 http.server 프로세스와 그 부모 프로세스를 트리로 보여 줬다.
4. 미리 보기. proc kill :3000 --dry-run --json 은 종료할 프로세스 1개를 JSON 으로 보여 줬다. 서버는 종료되지 않았다.
5. 오류. 사용하는 프로세스가 없는 포트를 지정하면 종료 코드 2 가 반환됐다. 잘못된 옵션, 범위를 벗어난 포트 번호, 잘못된 시그널 이름을 지정하면 4 가 반환됐다. 오류도 모두 JSON 으로 출력됐다. bash -c 로 proc kill 'proc kill' --dry-run 을 실행하자, 실행 명령에 proc kill 이 들어 있는 셸은 대상에서 제외됐다. 찾은 대상이 없어 종료 코드 2 가 반환됐다.
6. 확인 질문. 터미널에서 proc free :3000 을 실행하자 [y/N] 확인 질문이 출력됐다. 같은 명령에 --json 만 붙이자 확인 없이 프로세스를 종료했다. free 명령 문서에는 --yes 가 없으면 확인을 요청한다고 적혀 있다. 코드의 ask_confirm 함수는 --json 이면 확인을 건너뛴다.
7. 속도. 4코어 리눅스 컴퓨터에서 proc on :3000 --json 을 10번 실행했을 때 실제 경과 시간의 중앙값은 18 ms 였다. 같은 조건에서 lsof -t -i :3000 은 10 ms 였다.

README 에 적힌 JSON 출력 형식과 종료 코드는 권한 없음(3)을 제외하고 모두 확인됐다.

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

확인하지 못한 것

• macOS 와 Windows. proc 은 macOS 에서는 lsof 로 포트를 조회한다. macOS 와 Windows 에서 같은 시험을 하자.
• 에이전트 스킬. npx skills add yazeed/proc-cli 로 스킬을 설치하고, Claude Code 가 포트를 점유한 프로세스를 종료할 때 --dry-run 을 먼저 실행하는지 확인하자.
• 권한 없음(종료 코드 3). 다른 사용자의 프로세스를 대상으로 시험하자.

판정

작동한다. 포트 조회, 미리 보기, 종료 명령이 JSON 과 종료 코드를 반환했다. 다만 --json 을 붙이면 free 명령 문서와 달리 확인 없이 프로세스를 종료했다. 코딩 에이전트가 개발 서버를 자주 실행하고 정리하는 경우에 써 볼 만하다. 프로세스를 종료하기 전에 사용자의 확인을 받아야 하는 경우라면, --json 을 붙였을 때 proc 이 확인을 요청하지 않으므로 이 프로덕트는 적합하지 않다.