「pkill Claude Code process」の意味 — Claude Code
Claude Codeがpkillを拒否する「pkill pattern matches the Claude Code process」は、自分自身を巻き込むパターンから会話を守るガードです。仕組みと回避策をまとめます。
Claude Codeに古いプロセスの掃除を頼んだら「pkill: refusing to run」と拒否された、という経験がある人は少なくないはずです。原因はコマンドの書き方が間違っているのではなく、そのパターンがClaude Code自身のプロセスにも一致してしまうことです。実行すれば会話そのものが途中で強制終了しかねないため、Claude Codeはコマンドを実行する前に自らブレーキをかけます。
pkill pattern matches the Claude Code processとは何のエラーか
表示される文言は次のとおりです。
pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345).
Narrow the pattern, or target your own children with `pkill -P $$ ...`.BashツールでのCLIコマンドの中に、典型的には-fオプション付きのpkillがあり、そのパターンがClaude Codeのプロセスそのものにも一致するとき、この拒否が発生します。pkill -f nodeのように広いパターンで開発サーバーを一括終了しようとした場合、Claude Code自身もNode.jsプロセスとして動いていれば巻き込まれます。放置すれば、掃除のつもりのコマンドがセッションを道連れに終了させてしまいます。
どうやって自分自身への一致を検知しているか
Claude Codeはpkillを実際に実行する前に、同じパターンでpgrepを先に走らせて結果を確認します。その結果に自分自身のプロセスIDが含まれていれば、pkill本体の実行を拒否する仕組みです。実行してから被害を止めるのではなく、実行そのものを未然に防ぐ設計になっています。
この安全策には仕掛けがあります。Claude Codeは自身が起動するサブプロセス(BashツールとPowerShellツールのコマンド、hookコマンド)に対して自分の実プロセスIDを渡しています。渡す先の環境変数名はCLAUDE_PIDです。Linux上のBashツールのシェル統合は、このCLAUDE_PIDを使って、実行しようとしているpkillパターンが自分自身のプロセスに一致するかどうかを判定しています。
なぜ-f付きのパターンが事故を起こしやすいか
pkillの-fオプションは、プロセス名だけでなくコマンドライン全体を対象にパターンマッチングします。pkill -f nodeと書くと、node server.jsはもちろん、たまたまコマンドラインのどこかにnodeという文字列を含む無関係なプロセスまで巻き込みます。Claude Code自身もNode.jsのランタイム上で動作しているため、nodeのような一般的な文字列を含むパターンは、意図せずClaude Codeのプロセスにも一致してしまう典型例です。
対照的に、プロセス名の完全一致だけを対象にする-xオプションや、対象を実行ファイルのフルパスまで絞ったパターンであれば、一致範囲は大きく狭まります。このエラーに繰り返し当たる場合、パターンの絞り込み方を見直す価値があります。
| パターンの書き方 | 一致範囲 | 事故りやすさ |
|---|---|---|
pkill -f node | 一致範囲コマンドライン全体にnodeを含む全プロセス | 事故りやすさ高い(Claude Code自身も巻き込みやすい) |
pkill -f "node server.js" | 一致範囲コマンドライン全体が具体的な文字列に一致するプロセスのみ | 事故りやすさ中程度 |
pkill -P $$ | 一致範囲現在のシェルの子プロセスのみ | 事故りやすさ低い(自分が起動した範囲に限定) |
似た仕組みとの違い(サブプロセスの隔離)
pkillの自己終了ガードとは別に、Linux環境にはサブプロセスからホスト側のプロセスを見えなくする設定もあります。CLAUDE_CODE_SUBPROCESS_ENV_SCRUBを有効にすると、Bashのサブプロセスが独立したPIDネームスペースで実行されるようになります。副作用として、ps・pgrep・killはホスト側のプロセスを一切参照できなくなります。この設定はもともと機密情報の露出を減らす目的のものですが、結果的にpkillが自分自身に一致する余地そのものをなくす、より強い隔離策として働きます。日常的な安全策は本記事のpgrep事前チェックで足りますが、より厳格な隔離が必要な場面ではこちらも選択肢になります。
Linux限定という制約
このガードはLinux上でのみ動作します。macOSではpkillは無修正のまま実行されるため、自分自身に一致するパターンでも拒否されずに通ってしまいます。macOS環境で広いパターンのpkillを使う場合、Linuxのように自動でブレーキがかかることは期待できないため、パターン自体を狭く書く注意がより重要になります。
バージョンによる挙動の違い
このガード自体は比較的新しく追加された安全策です。
| バージョン | 挙動 |
|---|---|
| v2.1.214より前 | 挙動ガードが存在せず、自分自身に一致するパターンでもpkillがそのまま実行された。一致すれば会話が途中で強制終了していた |
| v2.1.214以降 | 挙動Linux上でpgrepによる事前チェックが働き、自分自身に一致するパターンは実行前に拒否される |
古いバージョンで運用しているCI環境や自動化パイプラインでは、意図せずpkill -fが自分自身のセッションを巻き込んで途中終了する事故が起きやすかった時期です。claude updateで最新化するだけで、このガードが自動的に効くようになります。
対処法
エラーメッセージ自体がすでに2つの選択肢を提示しています。
- パターンを絞り込む:
pkill -f nodeのような短い部分一致ではなく、対象プロセスのフルパスなど、より具体的な文字列に一致するパターンへ書き換える - 自分が起動した子プロセスだけを狙う:
pkill -P $$で、現在のシェルの子プロセスだけに一致範囲を限定する
実務上は、拒否された時点でClaude自身がパターンを調整して再試行することがほとんどです。エラーはBashツールの実行結果として返るだけでターミナルにバナーが出るわけではないため、ユーザーが気づかないうちに解決していることも珍しくありません。
Bashの権限設計との関係
このガードは、settings.jsonのpermissions.denyで書くBash(pkill *)のようなルールとは別の層にあります。denyルールはユーザーが明示的に設定する許可・拒否のリストで、パターンごとに設定を書かなければ効きません。一方、pkillの自己終了ガードはClaude Code側に組み込まれた既定の安全策で、設定を書かなくても最初から働きます。
この構造は、rmやrmdirが保護対象のパス(.gitや作業ディレクトリの外)を狙ったときに、どの許可ルールでも承認できない扱いになる仕組みと同じ発想です。ユーザー側の権限設定をどう組んでいても、Claude Code自身のプロセスを巻き込むコマンドや、破壊的すぎる一部の操作だけは別枠のガードで止められています。裏を返せば、pkillによるセッション終了を狙ってdenyルールを書かなくても、Linux環境であればこのガードがすでに機能しているということです。
よくある質問
Windowsでもこのガードは働きますか
公式ドキュメントが明記しているのはLinuxとmacOSの挙動だけです。Linuxではpgrepによる事前チェックが働き、macOSでは無修正のまま実行されます。Windows環境でpkillを使う場面自体が限られるため、判断に迷う場合はパターンを狭く書く前提で運用するのが安全です。
killコマンドを直接使った場合も同じガードが働きますか
このエラーの説明はpkillコマンドに限定されています。特定のプロセスIDを直接指定するkillは、パターンマッチングではなくID指定そのものが前提のコマンドのため、同じ仕組みの対象になるかは別問題です。プロセスの掃除は、可能な限りpkill -P $$のように自分が起動した子プロセスへ範囲を絞る書き方のほうが、意図しない事故を避けやすくなります。
CLAUDE_PIDはどのサブプロセスに渡されますか
Bashツール・PowerShellツールで実行されるコマンドと、hookコマンドに渡されます。Claude Code自身のプロセスIDが値として設定されており、v2.1.214以降のバージョンで利用できます。自作のhookスクリプトの中で「これは親のClaude Codeプロセスか」を判定したいときにも、同じ環境変数をそのまま読めば済みます。
長時間セッションほど注意が必要なのはなぜですか
開発サーバーやワーカープロセスを立てたまま長く動かすセッションほど、掃除のためにpkill -fのような広いパターンを使う場面が増えるためです。序盤の短いセッションでは意識しなくても済んだパターンの書き方が、動かしっぱなしのプロセスが増えるほどClaude Code自身を巻き込むリスクに変わります。日頃からpkill -P $$のように自分が起動した子プロセスへ絞る書き方を基本にしておくと、この種の事故を避けやすくなります。
CI環境でこのエラーに当たったらどうすればよいですか
CI環境がLinuxであれば、このガードが働くこと自体は事故防止として歓迎できる挙動です。対処は通常の場合と同じで、パターンを対象プロセスのフルパスに絞り込むか、pkill -P $$で自分が起動した子プロセスだけに範囲を限定します。CI上でClaude Codeプロセス自体を巻き込むpkill -fを書いていないか、まず洗い出すのが早道です。
まとめ
「pkill pattern matches the Claude Code process」は、pkillのパターンがClaude Code自身のプロセスにも一致してしまうときに出るエラーです。自己終了を防ぐための拒否だと理解しておけば十分です。掃除のつもりのコマンドが会話ごと終わらせてしまう事故を、実行前の一手間で未然に防ぐ仕組みだと理解しておくと、拒否された瞬間の戸惑いが減ります。Linux上でpgrepによる事前チェックが働き、v2.1.214以降のバージョンで有効になっています。macOSでは同じガードが働かないため、パターンを広く書きすぎない意識がより必要です。対処はパターンを具体的に絞り込むか、pkill -P $$で自分の子プロセスだけに範囲を限定するかの2択です。Bash(pkill *)のようなdenyルールを別途書かなくても、Linux環境ではこの安全策がすでに機能している点を覚えておくと、権限設計を考えるときの見通しが立てやすくなります。パーミッション全体の設計を確認したい場合はClaude Codeセキュリティ・権限ガイドが参考になります。settings.jsonの書き方はClaude Code settings.json完全ガイドにまとめています。