Windows: allow configuring the default session shell via config

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #15371
• #15294

Powered by Codex Action

A few implementation details that may help with review:

• codex-rs/config/src/types.rs
• adds windows.shell_path to WindowsToml

• codex-rs/core/src/config/mod.rs
• resolves profile.windows.shell_path before the top-level windows.shell_path
• validates the configured path on Windows during config loading
• surfaces a config error for unsupported / unusable executables instead of silently falling back

• codex-rs/core/src/codex.rs
• applies the configured shell path when constructing the default session shell
• keeps the existing internal precedence: user_shell_override still wins if one is already provided programmatically

• codex-rs/core/src/shell.rs
• adds a separate helper for configured shell paths instead of reusing the model-provided-path flow
• keeps the default behavior unchanged when no config value is present

• codex-rs/tools/src/local_tool.rs
• updates the Windows shell tool descriptions so they refer to the configured default shell instead of PowerShell-specific wording

• docs/config.md and codex-rs/core/config.schema.json
• document and expose the new config entry

A couple of scope boundaries are intentional here:

• this does not add arbitrary shell adapter support
• windows.shell_path must point to a shell executable already handled by Codex's built-in shell adapters
• at the moment that means the shell types Codex already knows how to detect and execute, such as bash, sh, zsh, pwsh, powershell, and cmd
• if windows.shell_path is unset, Windows behavior remains the same as today

I also added targeted coverage for:

• loading windows.shell_path from config
• profile override behavior
• invalid configured shell paths failing config load
• Windows shell resolution using a configured bash.exe
• retaining the existing PowerShell default when no config is provided

Just dropping a +1 with a real consumer use case. I maintain winuxsh (https://github.com/unixwin/winuxsh), a Windows-native bash/zsh-like shell (rubash + winuxcmd, no MSYS/Cygwin/WSL layer). We have already verified that winuxsh -c "<cmd>" meets the agent non-interactive contract: no banner, clean stdout/stderr, exact exit code, native Windows paths and ~ resolution. We have users who would switch to Codex specifically if shell_command could route to winuxsh instead of PowerShell.

Everything your PR proposes is exactly what we need:

• windows.shell_path = "..." as the single config entry point
• profile override of the top-level value
• validation via the existing built-in shell detection logic
• fallback to current behavior when unset

One thing worth confirming: my winuxsh uses -c "<command>" for non-interactive mode (same as bash/zsh). Looking at codex-rs/core/src/shell.rs, derive_exec_args currently branches on ShellType and would route a custom path through the Cmd branch (/c <command>) if detect_shell_type falls back. Would the PR validation reject an unknown stem like winuxsh.exe, or is there room to add a bash/sh-compatible branch (i.e. -c rather than /c) when the configured path matches a known Unix-style shell?

Happy to help test a build or contribute test cases if it helps move this forward.

I would strongly benefit from this feature, specifically with Cygwin Bash:

[windows]
shell_path = "C:\\cygwin64\\bin\\bash.exe"

I launch Codex from Cygwin, but native Windows Codex still runs agent commands through PowerShell. I can instruct it to invoke Cygwin Bash for each command, but that is not an equivalent substitute for making Bash the actual session shell.

Claude Code supports this workflow through CLAUDE_CODE_GIT_BASH_PATH, and I use it successfully with C:\cygwin64\bin\bash.exe. Commands run directly in Cygwin, so POSIX scripts, paths, tools, skills, and permission rules behave consistently.

The PowerShell-to-Bash wrapper approach has several drawbacks:

• It adds extra process and shell startup overhead to every short agent command.
• It introduces a second quoting and path-translation layer, making pipes, redirects, multiline commands, heredocs, and complex arguments less reliable.
• It makes POSIX-oriented skills and their scripts/ directories fragile, because a script may accidentally be sent directly to PowerShell.
• It makes command approval and prefix rules less useful because PowerShell sees only a Bash-launch command, not the actual POSIX command.
• It requires an instruction-following workaround instead of a reliable tool-level configuration.

WSL is not a drop-in replacement for every Windows-native project. Keeping a repository on C:\... while running Linux tools can cause significant cross-filesystem I/O overhead. Moving a project into WSL can also require changes to paths, toolchains, editor and debugger setup, environment variables, services, and Windows-specific build or automation dependencies.

Cygwin is the best fit for some of my existing Windows-native projects. Please consider accepting a Cygwin bash.exe path for windows.shell_path, provided it passes the existing Bash shell detection and execution checks.

I'd also support this. My main reasons are:

• Models are generally much more familiar with Bash than with PowerShell, which tends to result in more reliable shell commands.
• PowerShell startup/execution is extremely slow on my machine, so shell-heavy agent workflows noticeably suffer.
• Requiring WSL just to get a Bash environment feels unnecessarily heavyweight, especially when Git Bash is already readily available on many Windows development setups.

There are also a couple of closely related issues:

• #13165 asks for choosing the shell on Windows, specifically mentioning MinGW Bash as an alternative for users who don't want WSL.
• #16717 proposes configurable PowerShell/Git Bash support.

So I think an explicit windows.shell_path as proposed here would be a useful and fairly general solution, while preserving PowerShell as the default for existing users.