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コマンドをセッションの次プロセスへ引き継ぐ土台になっています。変数を立てると、この引き継ぎが起きなくなります。

既定動作: バックグラウンドコマンドがセッションの次プロセスへ引き継がれる

Claude Codeは長時間実行するコマンドをrun_in_background: trueでバックグラウンドタスクとして起動でき、一覧と停止は/tasksで行えます。セッション自体をバックグラウンド化する操作(←キーや/background)を行うと、そのセッションはsupervisor(スーパーバイザー)というバックグラウンドサービスの下で動くプロセスに切り替わります。

supervisorは、セッションのプロセスが停止・再起動したとき、そのプロセスが起動していたバックグラウンドのシェルコマンドやワークフローを次のプロセスへ引き継ぎます。Windowsでは、cmd.exeランチャーを経由することで、バックグラウンドPowerShellコマンドの引き継ぎが可能になっています。

変数を立てるとどう変わるか

CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER=1を設定すると、PowerShellコマンドはランチャーを介さず直接起動します。この状態でバックグラウンドPowerShellコマンドを動かしている最中にセッションのプロセスが終了すると、そのコマンドもそこで止まります。次のプロセスへの引き継ぎは起こりません。

公式ドキュメントが明記する範囲は次の3点です。

• 影響が及ぶのはPowerShellコマンドのみで、Bashコマンドは対象外
• 適用にはClaude Code v2.1.269以降が必要
• 既定(変数を設定しない状態)では、セッションをバックグラウンド化するなど、セッションのプロセスが入れ替わる場面でPowerShellコマンドが次のプロセスへ引き継がれる

セッションを開いたまま←や/backgroundでバックグラウンド化する運用や、supervisorがアップデート後にプロセスを再起動する場面では、既定のままだと動かしていたPowerShellの処理が水面下で生き続けます。ログ収集や監視目的でバックグラウンドPowerShellを使っているなら、この生存自体が意図した挙動かどうかを確認する価値があります。特に.ps1スクリプトやモジュールをバックグラウンドで動かしているケースでは、セッションを閉じたつもりでも処理そのものは残り続けている点に気づきにくくなります。

セッションのプロセスはいつ入れ替わるか

「引き継ぎが起きる場面」はセッションを手動でバックグラウンド化したときだけではありません。supervisorは次の条件でもセッションのプロセスを止めたり再起動したりします。

• セッションが終了または返答待ちの状態で、約1時間アタッチされていないとき(リソース解放のため停止)
• Claude Codeの自動アップデート後、supervisorが新しいバージョンへ自分自身を再起動し、アイドル中のセッションを移し替えるとき
• セッションのプロセスがsupervisor稼働中に予期せず終了したとき(supervisorが再起動する)

このうち自動アップデート後の移し替えでは、作業中・返答待ち・アタッチ中のセッションは中断されません。移し替えの対象になるのはアイドル状態のバックグラウンドセッションだけです。Windows環境でPowerShellの長時間コマンドを走らせたまま席を離れる運用では、約1時間のアイドル後や自動アップデート後の入れ替わりのたびに既定動作(引き継ぎ)が働いていることになります。

使い分け早見表

CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFとの違い

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

CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFはBashコマンドやワークフロー、サブエージェントまで含めて引き継ぎを止める汎用スイッチです。ただし公式ドキュメントは、この変数が効くのはsupervisorがセッションのプロセスを停止・再起動・アップデートする場面だけだと明記しています。←キーや/backgroundで自分からセッションをバックグラウンド化した場合は、CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFを設定していても引き継ぎは止まりません。Windows上のPowerShellコマンドについては事情が異なり、CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHERを設定しておけば、手動でのバックグラウンド化を含めて引き継ぎ自体が起きなくなります。

この変数が効く典型的な場面

Windows端末でClaude Codeを使い、PowerShellでログ監視スクリプトをrun_in_background: trueで動かしているとします。作業が一段落したのでセッションを←キーでバックグラウンド化し、別の作業に移りました。この時点でセッションはsupervisorの管理下に移り、監視スクリプトは既定のcmd.exeランチャー経由で動いているため、セッションのプロセスが入れ替わってもそのまま動き続けます。

ここでもし監視スクリプトが不要になった、あるいは対象のログファイルへの参照を保持し続けるのが困る事情があるなら、CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHERを設定しておきます。すると、セッションのプロセスが停止するタイミング(約1時間のアイドル後や自動アップデート後の再起動)に合わせて、PowerShellのプロセスも一緒に終了します。逆に、意図的に長時間動かし続けたい監視・ビルド系のジョブであれば、既定のまま(変数を設定しない)にしておくほうが目的に合います。

設定方法

環境変数はシェルで一時的に設定するか、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を入れた環境ではclaude.aiとConsoleアカウントで既定有効、Amazon Bedrock・Google CloudのAgent Platform・Microsoft FoundryではCLAUDE_CODE_USE_POWERSHELL_TOOL=1を別途設定する必要があります。ツール自体が無効な環境では、CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHERを設定しても対象のPowerShellコマンドが存在しないため意味を持ちません。

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

よくあるつまずき

• Bashにも効くと思い込む: 対象はPowerShellコマンドだけで、Bashコマンドの引き継ぎ挙動は変わりません
• 設定したのに変化がない: Windows以外(Linux・macOS・WSL)では、PowerShellツールを有効にしていてもこのランチャー自体が存在しないため設定の意味がありません。なお、これらの環境でPowerShellツールを使うにはPowerShell 7以降(pwsh)をインストールし、PATHに通しておく必要があります
• PreToolUseフックがPowerShellコマンドを見逃す: Bashだけにマッチさせているカスタムフックは、この変数の設定有無にかかわらずPowerShellツールのコマンドを検知できません。両方を捕捉するにはBash|PowerShellでマッチさせる必要があります
• メモリ制限の変数と混同する: 似た用途の環境変数にCLAUDE_CODE_TOOL_MEMORY_LIMITがありますが、こちらはBash・PowerShellのメモリ使用量を制限するもので、プロセスの引き継ぎとは別の話です

まとめ

CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHERは、Windows上でPowerShellコマンドをcmd.exeランチャー経由にせず直接起動させ、セッションのプロセスが終了したときにバックグラウンドPowerShellコマンドを一緒に止める変数です。Bashコマンドには影響しません。バックグラウンドのPowerShellを確実に終了させたい人はこの変数を、Bashやワークフロー、サブエージェントまで含めて引き継ぎを止めたい人はCLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFを検討してください。適用にはClaude Code v2.1.269以降が必要で、PowerShellツール自体が有効になっている環境でのみ意味を持ちます。