feat: configurable Windows agent shell (powershell/git-bash)
Resolved 💬 12 comments Opened Apr 3, 2026 by Jawad-hussain-kalwar Closed May 10, 2026
💡 Likely answer: A maintainer (github-actions[bot], contributor)
responded on this thread — see the highlighted reply below.
Problem
On Windows, Codex hardcodes PowerShell as the agent shell. PowerShell syntax is unfamiliar to the model compared to bash, leading to worse command generation. Users with Git Bash installed have no way to switch.
Proposed Solution
Add a [windows].agent_shell config key ("power-shell" | "git-bash") to ~/.codex/config.toml:
[windows]
agent_shell = "git-bash"When git-bash is selected:
- Agent default shell resolves to bash (with Git for Windows fallback paths)
- Tool descriptions sent to the model switch to bash syntax examples
- Hard error on session start if bash is configured but not found
- Bash binary registered as sandbox-readable root
Default behavior (PowerShell) is unchanged when the key is omitted.
Implementation
I have a working implementation in my fork with all tests passing:
- Branch: https://github.com/Jawad-hussain-kalwar/codex/tree/feat/configurable-windows-agent-shell
- PR (fork): https://github.com/Jawad-hussain-kalwar/codex/pull/1
- 14 files changed, 266 insertions, 14 deletions
cargo test -p codex-tools— 59 passed, 0 failedcargo test -p codex-core --lib— 1558 passed, 0 failed from these changes
The implementation follows existing config patterns ([windows].sandbox, [windows].sandbox_private_desktop) and the zsh-fork shell resolution precedent.
12 Comments
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
Have you tried just steering the model to use bash? It tends to use PowerShell because many Windows users don't have git bash, but if you ask it to use bash, it should do so.
I have tried it, I have tried adding it to global rules, it sitll tends to use powershell, the limitation is the functions.shell_command tool by default it is only configured to be powershell so even if agent tried to use gitbash it will do so via powershell and then use bash.exe followed by command and it makes its performance even worse and token usage is also wasted,
This feature request hasn't received enough upvotes, so I'm going to close it.
The fact that there is an option in the windows app for choosing the "integrated shell" is confusing, took me a very long time to realize that the choice there has no bearing on the terminal shell used by the agent.
@sicora-at-mcgough, you are welcome to open a new issue. Sometimes a feature request doesn't attract upvotes because of the way it's titled or described, so opening a new one can help attract more support.
@etraut-openai Why does a basic feature like letting users choose which shell the agent uses need a certain number of upvotes? It's the kind of option that should have been there from the start, in the very first version.
It's a blocking issue for environments where users need a bash-like shell for their workflows, and have git-bash/cygwin etc. installed, but don't have admin rights to install WSL.
It would be preferable if we had the ability to choose the type of shell (to tell the agent which kind of commands to generate) as well as the path to the shell tool (like #16579), or at least have codex honor
$SHELL, if it's set.There's 20 upvotes on this issue, plus it seems like an obvious thing to fix, (at least obvious to Windows users). Is that really not enough to fix this problem?
I just ran a script that looked through my Codex history at all the times that it had, behind-the-scenes, got a command wrong, or messed up quoting for PowerShell, and either got confused and headed down the wrong path. It's a lot!
I suspect if a certain subset of OpenAI employees used Windows and noted the same thing, they'd see how suboptimal it is right now and accept this fix.
Or even better than allowing Git Bash would be to train the model to use PowerShell. Surely that's the long-term win.
dude, claude code supported git-bash long time ago, is it very hard ?
@etraut-openai I hope I can support it. There are already multiple issue.
wish Git‑Bash can be integrated sooner.