CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHERでPowerShellを直接起動

CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHERとは

CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHERは、Windows上のPowerShellツールが使うcmd.exeランチャーを無効にする環境変数です。1を設定すると、PowerShellコマンドはcmd.exeを経由せず直接起動されます。Claude Code v2.1.269以降で使えます。

既定では、Claude CodeはWindows上のPowerShellコマンドをcmd.exeランチャー経由で起動します。このランチャーのおかげで、バックグラウンドで動かしたPowerShellコマンドがセッションの次のプロセスへ引き継がれます。変数を立てると、この引き継ぎが起きなくなります。

変数を立てる前後でバックグラウンドPowerShellはどうなるか

影響が及ぶのはPowerShellコマンドだけで、Bashコマンドは対象外です。PowerShellコマンドのバックグラウンド実行は、Claudeがrun_in_background: trueを付けて起動する長時間コマンドのことで、一覧と停止は/tasksから行えます。

ログ収集や監視にバックグラウンドPowerShellを使っている場合、既定のままだと、セッションのプロセスが入れ替わったあとも処理が生き続けます。.ps1スクリプトやモジュールを動かしているときほど、セッションを閉じたつもりで処理が残っていることに気づきにくくなります。

「次のプロセス」ができるのはいつか

変数の効き目が出るのは、セッションのプロセスが入れ替わる瞬間です。最も分かりやすいのは、自分でセッションをバックグラウンド化する場面です。

ターミナルから最初からバックグラウンドで始めるclaude --bgでも、セッションはsupervisor(バックグラウンドサービス)の管理下で動きます。v2.1.289のclaude --helpには、--bgについて「セッションをバックグラウンドで開始してすぐ戻り、claude attach・logs・stop・rmで使うIDを表示する」と書かれています。

claude --bg
claude agents

手動のバックグラウンド化以外にも、supervisorがプロセスを止めたり再起動したりする場面があります。

• 終了済み、またはこちらの返信待ちの状態で、約1時間アタッチされていない(リソース解放のために停止。Ctrl+Tでピン留めするとプロセスは動き続けます)
• 自動アップデートのあと、supervisorが新バージョンに自分を再起動し、アイドル中のセッションを移し替える(作業中・返信待ち・アタッチ中のセッションは中断されません)
• supervisor稼働中にプロセスが予期せず終了し、再起動される

←や/backgroundで自分からバックグラウンド化したセッションをkillで終わらせた場合は、再起動されずに停止扱いになります。

Windowsでバックグラウンド実行のPowerShellを動かしたまま席を離れる運用では、約1時間のアイドル停止や自動アップデートの際に、既定の「引き継ぎ」が働きます。

引き継ぎの対象は、バックグラウンドのシェルコマンド、動的ワークフロー、バックグラウンドのサブエージェントです。実行中のモニターと、サブエージェントが起動したシェルコマンドは、プロセスと一緒に止まります。

使い分け早見表

CIやクラウドセッションのような無人実行では、バックグラウンドのBashとPowerShellコマンドに時間制限が付きます。Claudeが起動したコマンドは既定で30分、run_in_backgroundと一緒に渡すtimeoutで最大2時間までです。この制限はv2.1.285以降にあり、v2.1.288より前はすべてのセッションに適用されていました。ターミナルやデスクトップアプリ、VS Code拡張で手元から使うセッションには時間制限がありません。

CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFとの違い

似た名前の変数にCLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFがあります。どちらも「セッションのプロセスが入れ替わるときに何かを引き継がせない」ための変数ですが、対象範囲が違います。

CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFが効くのは、supervisorがセッションのプロセスを停止・再起動・アップデートする場面だけです。←や/backgroundで自分からバックグラウンド化した場合は、この変数を1にしていても引き継ぎは止まりません。

手動のバックグラウンド化のときに進行中の作業を止めたいなら、別の環境変数CLAUDE_DISABLE_ADOPT=1があります。設定すると、Claude Codeは作業を引き継がず、バックグラウンド化の前に確認を求めます。

CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFが止めるsupervisor側の引き継ぎも、この変数はあわせて止めます。

設定方法

環境変数はシェルで一時的に設定するか、settings.jsonのenvブロックに書いて恒久化できます。

$env:CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER = "1"
claude

すべてのセッションに常時適用したい場合は、~/.claude/settings.json(自分専用)や.claude/settings.json(プロジェクト共有)に追記します。

{
  "env": {
    "CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER": "1"
  }
}

.claude/settings.jsonに書けばリポジトリにチェックインされ、同じプロジェクトで作業する全員に適用されます。個人の端末だけに適用したいなら~/.claude/settings.jsonか.claude/settings.local.jsonを使います。

シェルで設定した値は、そのターミナルセッションだけで有効です。常に効かせたい場合は、Windows PowerShellなら[Environment]::SetEnvironmentVariableでユーザー環境変数にするか、settings.jsonのenvブロックに置きます。

前提: PowerShellツールが有効になっている

この変数はPowerShellツールがすでに有効なことが前提です。有効になる条件は環境で分かれます。

• Git BashをインストールしていないWindows: 自動的に有効
• Git Bashを入れたWindows: claude.aiとConsoleアカウントでは既定で有効。Amazon Bedrock・Google CloudのAgent Platform・Microsoft FoundryではCLAUDE_CODE_USE_POWERSHELL_TOOL=1が必要
• Linux・macOS・WSL: 任意で有効化(PowerShell 7以降のpwshをPATHに通す)

ツールが無効な環境では、対象のPowerShellコマンドが存在しないため、この変数を設定しても意味を持ちません。

Windowsでは、Claude CodeはPowerShell 7以降(pwsh.exe)を優先して検出し、見つからなければPowerShell 5.1(powershell.exe)にフォールバックします。ツールが有効な間はPowerShellが主シェルとして扱われ、Git Bashが入っていればPOSIX向けのスクリプトはBashツールでも実行できます。Claude CodeのシェルとPowerShellの起動設定に、zsh・bash・PowerShellの切り替え全体があります。

よくあるつまずき

• Bashにも効くと思い込む: 対象はPowerShellコマンドだけで、Bashコマンドの引き継ぎ挙動は変わりません
• Windows以外で設定する: この変数はWindowsのPowerShellツールが使うcmd.exeランチャー向けです。Linux・macOS・WSLでPowerShellツールを使う場合に必要なのは、pwshのインストールとPATHの設定です
• PreToolUseフックがPowerShellコマンドを見逃す: Bashだけにマッチさせたフックは、この変数の設定有無にかかわらずPowerShellツールのコマンドを検知できません。両方を捕捉するにはBash|PowerShellでマッチさせます
• Bashのdenyルールを足したらPowerShellが消えた: Git Bashを入れたWindowsで、Bash(git push *)のような範囲指定を含むdenyルールを置くと、そのセッションではPowerShellツールがオフになります。残すにはCLAUDE_CODE_USE_POWERSHELL_TOOL=1を設定するか、PowerShell(git push *)のような個別のdenyルールを加えます
• メモリ制限の変数と混同する: CLAUDE_CODE_TOOL_MEMORY_LIMITはBash・PowerShellのメモリ使用量を制限する変数で、プロセスの引き継ぎとは別の話です

まとめ

PowerShellコマンドだけを、確認ダイアログなしで元のプロセスの終了と一緒に止めたいならCLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER=1です。Bashやワークフロー、サブエージェントまで止めたいときは、別の変数を使います。手動のバックグラウンド化ならCLAUDE_DISABLE_ADOPT=1(確認ダイアログあり)、supervisorの停止・再起動ならCLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFです。