proc-cli

proc CLI — プロセス管理ツール

proc は、macOS、Linux、Windows でプロセスやポートを扱うためのセマンティック CLI です。ポート（:3000）、PID、名前、ファイル、ディレクトリを指定でき、すべてのコマンドで単一の JSON ドキュメントを返せます。

開始する前に

• インストールされているか確認します：proc --version。このスキルは proc 1.14.3 を対象としています（proc inspect と uptime_secs には 1.14 以降が必要です）。
• インストールされていない場合は、インストールする前にユーザーに確認します。選択肢：brew install yazeed/proc/proc（macOS）、cargo install proc-cli、npm install -g proc-cli、scoop bucket add proc https://github.com/yazeed/scoop-bucket-proc && scoop install proc（Windows）、または nix profile install github:yazeed/proc。

重要なルール

1. 構造化出力を得るため、すべてのコマンドに 必ず --json を渡します
2. 対話型プロンプトをスキップするため、破壊的なコマンドには 必ず --yes を渡します
3. 破壊的な操作の前に --dry-run を使用して、実行される内容を確認します
4. 終了コードを確認します：0=成功、1=一般エラー（部分的な失敗や wait のタイムアウトを含む）、2=見つからない、3=権限がない、4=入力が無効です。"success": false の場合、終了コードは必ず 0 以外になります
5. --json を指定した場合、無効なフラグや引数も含め、エラーは標準出力に {"action":"<cmd>", "success":false, "error":"...", "exit_code":N} を出力します
6. watch ストリームを除き、JSON レスポンスはすべて単一のドキュメントで、action（エイリアスを解決したコマンド名）と success フィールドを含みます
7. 自分が起動したプロセス、またはユーザーが指定したプロセスだけを操作します。ポートや PID での指定を優先し、名前で指定する場合は --in <dir> または --by <name> で範囲を限定します
8. 終了コード 3 は昇格した権限が必要であることを意味します。sudo で再試行する前にユーザーに確認します

次のコマンドの代わりに proc を使用

代わりに使用するコマンド	使用するコマンド
lsof -i :3000、netstat -tlnp、ss -tlnp	proc on :3000 --json、proc ports --json
lsof -ti :3000 | xargs kill -9	proc free :3000 --yes --json（プロセスを終了し、ポートが解放されたことを確認します）
ps aux | grep node、pgrep -f node	proc by node --json、または複数のパターンの場合：proc list 'node,vite' --json
pkill -f pattern	proc kill pattern --in . --dry-run --json を実行してから、同じコマンドに --yes を付けて実行
kill PID、kill -9 PID	proc stop PID --yes --json、proc kill PID --yes --json
kill -STOP / kill -CONT	proc freeze / proc thaw
while kill -0 $PID; do sleep 1; done	proc wait PID --timeout 60 --json
lsof /path/to/file	proc for /path/to/file --json
pstree、ps -o ppid=	proc tree PID --json、proc why PID --json
top、ps aux --sort=-%cpu	proc list --sort cpu --limit 10 --json

ターゲットの構文

ほとんどのコマンドで、同じ形式のターゲットを指定できます。

• :3000 — ポート 3000 で待ち受けているプロセス
• 1234 — PID が 1234 のプロセス
• node — 名前が「node」に一致するプロセス（名前とコマンドラインを部分一致で検索）
• :3000,:8080,node — カンマ区切りの複数のターゲット。PID ごとに重複を除外します

例外：proc free はポートのみ、proc for はファイルパス、proc in はディレクトリを受け取ります。

ユーザーが入力する場合のエイリアス：:（on）、f（for）、b（by）、l/ps（list）、i/inspect（info）、p（ports）、k（kill）、s（stop）、t（tree）、w/top（watch）、x（stuck）、u（unstick）、o（orphans）。JSON の action には常に正式名称が使われます。

コマンド

検出（読み取り専用。--yes は不要）

proc on :3000 --json              # what process is on port 3000?
proc on 1234 --json               # what ports does PID 1234 use?
proc on node --json               # what ports are node processes using?
proc for ./server.py --json       # what's running (or holding open) this file?
proc by node --json               # find processes by name
proc by node --in . --json        # ...started from the current directory
proc in . --json                  # all processes whose cwd is under this directory
proc in ~/project --by node --json
proc list --json                  # all processes
proc list --min-cpu 10 --json     # processes using >10% CPU
proc list --status stopped --json # frozen/stopped processes
proc list --path /usr/local/bin --json  # filter by executable path
proc info :3000,1234 --json       # inspect one or more targets: full details
proc ports --json                 # all listening ports
proc ports --exposed --json       # only ports bound to 0.0.0.0 / ::
proc ports --local --json         # only ports bound to 127.0.0.1 / ::1
proc ports --range 3000-3999 --json
proc why :3000 --json             # trace ancestry — why is this port busy?
proc tree node --json             # descendants of node processes
proc tree 1234 --ancestors --json # path from the top ancestor down to PID 1234
proc orphans --in . --json        # processes whose parent died (reparented to PID 1)
proc stuck --json                 # processes >50% CPU running longer than --timeout (default 300s)

プロセスを調べるには、proc info を使用します（エイリアス：inspect、i。JSON の action は常に "info" です）。各ターゲットについて、名前、PID、コマンドライン、実行ファイルのパス、作業ディレクトリ、ユーザー、親 PID、ステータス、CPU、メモリ、開始時刻、稼働時間を報告します。list、by、in は、多数のプロセスについて同じフィールドを一度に返します。

ライフサイクル（破壊的な操作 — 常に --yes --json を使用）

proc kill :3000 --yes --json               # force kill (SIGKILL)
proc kill node --in . --graceful --yes --json  # SIGTERM instead of SIGKILL
proc stop node --yes --json                # SIGTERM, then SIGKILL after --timeout (default 10s)
proc stop nginx --signal HUP --yes --json  # send a different initial signal
proc freeze node --yes --json              # pause (SIGSTOP)
proc thaw node --yes --json                # resume (SIGCONT)
proc free :3000 --yes --json               # kill + verify port is free (--wait, default 10s)
proc free :3000,:8080 --yes --json         # free multiple ports
proc unstick 1234 --yes --json             # SIGCONT then SIGINT; no kill
proc unstick 1234 --force --yes --json     # ...then SIGTERM, SIGKILL if still stuck
proc orphans --in . --kill --yes --json    # kill orphans whose cwd is under this directory

監視

proc wait node --timeout 60 --json       # block until all node processes exit (max 60s)
proc wait :3000 -n 1 -q --timeout 30 --json  # poll every 1s, quiet
timeout 10 proc watch node --json        # NDJSON stream, one object per refresh (-n seconds)

手順

ポートが使用中（EADDRINUSE、「address already in use」）

proc on :3000 --json        # who holds it? check name, cwd and command
proc why :3000 --json       # what started it (ancestry)
proc free :3000 --yes --json  # only if it's yours or the user agreed

ポートを使用しているのがユーザー自身のアプリ、別のプロジェクト、または別のエージェントのサーバーである場合は、ポートを解放する前に確認するか、別のポートで起動します。

サーバーまたはジョブをバックグラウンドで実行し、その後クリーンアップする

• 起動時にポートまたは PID を控えておきます。その対象を指定して停止します：proc stop :4789 --yes --json または proc kill 12345 --yes --json。
• 入力したコマンドから名前パターンをコピーして停止しないでください。実際のコマンドラインは異なることがよくあります（bunx serve は node …/serve として実行されます）。そのため、パターンに一致するプロセスがなくても気づかないことがあります。
• kill と stop がシグナルを送るのは、指定したプロセスだけであり、その子プロセスには送りません。npm run dev を kill すると、node または ts-node の子プロセスが残る場合があります。proc tree PID --json を確認して子プロセスも対象にするか、ポートを指定して停止してください。
• 停止したことを確認します：何もリッスンしていない場合、proc on :4789 --json は 2 で終了します。

タスクを終える前に、残っているプロセスを確認する

proc ports --in <project-dir> --json      # servers you left listening
proc orphans --in <project-dir> --json    # processes whose parent already exited
proc list 'headless,ms-playwright,puppeteer' --json   # headless browsers

--in はプロセスの作業ディレクトリに一致するため、プロセスが実行されていたディレクトリ（cd した先）を指定します。これは自身の cwd とは異なる場合があります。残っているプロセスを停止する前に、proc why PID --json を確認してください。そのプロセスの祖先をたどると別のエージェントセッション、エディター、またはユーザーのターミナルにつながる場合は、自分のプロセスではありません。停止せず、報告してください。

マシンの動作が遅い

proc list --sort cpu --limit 10 --json
proc list --min-mem 1000 --sort mem --json   # over 1 GB
proc stuck --json                             # sustained high CPU

各プロセスの cwd、uptime_secs、parent_pid を含め、確認した内容を報告して、停止するプロセスはユーザーに判断してもらってください。

クリーンに再起動する

proc stop :3000 --yes --json   # SIGTERM, SIGKILL after 10s
proc on :3000 --json           # exit 2 = nothing listening; safe to start again

proc free :3000 --yes --json は、SIGTERM を送信し、最大 5 秒後に SIGKILL を送信してから、ポートが解放されたことを確認します。自動終了が見込まれるプロセスには proc wait を使います。一致するプロセスがない場合は、すぐに 2 で終了します。

安全性

• 名前による対象指定は、proc が確認できるすべてのプロセスのうち、名前またはコマンドラインにパターンが含まれるものに一致します。ほかのプロジェクト、エディター、ユーザーのターミナル、ほかのエージェントの MCP サーバーやブラウザーも対象になります。名前で対象を指定する場合は、必ず最初に --dry-run を実行し、--in で範囲を限定してください。
• proc は、名前による一致で自身のプロセスと親プロセスの連鎖（最大 10 階層）を対象にしません。そのため、エージェント内で proc by claude を実行すると、そのエージェントは対象から除外されます。PID とポートによる対象指定には、この保護はありません。
• 最初から kill（SIGKILL）を使わないでください。プロセスがクリーンアップする時間を確保できる stop を優先してください。

フィルター

すべてのコマンドがすべてのフィルターに対応しているわけではありません。proc <cmd> --help を確認してください。

フィルター	コマンド
--in [dir]（-i、既定値は .）	why、free、in 以外すべて
--by <name>（-b）	why、free、by、list 以外すべて（この 2 つでは名前を引数として指定します）
--min-cpu <pct>、--min-mem <MB>	list、by、in、for、tree、watch
--status <s>（running、sleeping、stopped、zombie）	list、by、in、for、tree
--min-uptime <secs>	list、by、in、for、tree
--parent <pid>	list、by、in
--path <path>（-p、実行ファイルのパス）	list
--sort <key>（cpu、mem、pid、name）	list、by、in、for、watch
--sort <key>（port、pid、name）	ports
--limit <n>（-n、watch では -l）	list、by、in、for、ports、watch
--depth <n>（-d、既定値は 10）、--compact（-C、PID のみ）	tree

出力スキーマ

完全な JSON 出力スキーマとフィールド定義については、reference.md を参照してください。プロセスで最もよく使うフィールドは、pid、name、command、cwd、parent_pid、user、status、cpu_percent、memory_mb、start_time、uptime_secs です。

エージェント／パイプの準備状況

• 単発クエリ：on、for、by、in、list、info、ports、why、tree、orphans、stuck — すぐに返ります
• ブロッキング：proc wait — 必ず --timeout を指定してください
• ストリーミング：proc watch --json — NDJSON を無期限に出力します。timeout N または | head -n N で制限してください。--json なしで TTY もない場合は、スナップショットを 1 回だけ出力します。スナップショットを 1 回だけ取得する場合は、proc list を優先してください
• 破壊的操作：kill、stop、freeze、thaw、free、unstick、および --kill を指定した orphans／stuck — 必ず --yes --json を指定してください
• ユーザーへの結果表示：読みやすい表を表示するには --json なしで実行してください（幅 100 文字以上のターミナルでは UPTIME 列が表示されます）

注意事項

• ポートの指定は : で始める必要があります。proc on 3000 はポート 3000 ではなく、PID 3000 を検索します。
• proc free が受け付けるのはポートの指定（:3000）のみです。名前や PID を指定する場合は proc kill を使ってください。
• 名前の照合は部分文字列で行われます。proc by node は「node」、「nodejs」、「nodemon」に一致します。--in で絞り込むか、PID を使ってください。
• proc by に指定できるパターンは 1 つですが、proc list には複数のパターンをカンマ区切りで指定できます：proc list 'git commit,pre-commit' --json。パターンは正規表現ではなく、名前とコマンドライン全体に対して照合される、大文字と小文字を区別しない単純な部分文字列です。
• JSON の uptime_secs は稼働時間（秒）です。start_time は Unix タイムスタンプであり、経過時間ではありません。
• 削除されたディレクトリ（たとえば、削除済みのワークツリー）でプロセスが実行され続けることがあり、そのようなプロセスが探している残存プロセスであることもよくあります。proc 1.14.1 以降では、proc in <dir> でそのようなプロセスを一覧表示でき、cwd には通常のパスが表示されます。1.14.0 以前では、削除済みのディレクトリを指定すると proc in <dir> は終了コード 4 で拒否されるため、代わりに proc list --in <dir> または proc orphans --in <dir> を使ってください（macOS の場合。Linux では、カーネルが作業ディレクトリを <dir> (deleted) と報告するため、これらのバージョンでは該当プロセスを検出できません）。
• --dry-run --json は、影響を受けるプロセスを示す "processes" とともに "dry_run": true を出力します。変更は行われません。
• proc orphans --kill と proc stuck --kill は、proc kill と同様に（succeeded／failed）を報告し、action はそれぞれ "orphans"／"stuck" になります。
• kill／stop／freeze／thaw／orphans --kill／stuck --kill でいずれかのプロセスの処理に失敗すると、終了コードは 1 になり、failed に失敗理由が示されます。succeeded に含まれるプロセスには、引き続き処理が実行されています。
• proc wait がタイムアウトすると、timed_out: true を含む結果を出力し、終了コード 1 で終了します。
• --signal を指定できるのは proc stop のみです。有効なシグナルは HUP、INT、QUIT、ABRT、KILL、TERM、STOP、CONT、USR1、USR2 です（SIG の有無、大文字と小文字は問いません）。
• --graceful を指定できるのは proc kill のみです。
• 不明なフラグを指定すると終了コード 4 になります。--json を指定した場合、エラーは標準出力に JSON オブジェクトとして出力され、それ以外の場合は標準エラーにプレーンテキストで出力されます。
• freeze と thaw は Unix 専用です。Windows では終了コード 1 で失敗します。
• proc stuck は、CPU 使用率の高い状態が続いていることを基準とするヒューリスティックであり、ハングを検出するものではありません。
• 孤児プロセス（親 PID が 1）だからといって、必ずしも放棄されたプロセスとは限りません。デーモンや tmux／nohup のジョブは意図的に孤児化されます。残存プロセスと判断する前に、cwd、command、稼働時間を確認してください。