mirror of
https://github.com/badlogic/pi-mono.git
synced 2026-11-05 23:37:25 +00:00
25426f72ae
Adds a "Choose a terminal" section to `packages/coding-agent/docs/windows.md` (https://pi.dev/docs/latest/windows), with two tables (last updated October 2026): - Terminals and which conhost they use: Windows Terminal (recommended), VS Code, WezTerm nightly (bundled, up to date); WezTerm 20240203 (bundled, old); Alacritty (built-in unless `conpty.dll` + `OpenConsole.exe` are provided); classic console window, mintty, ConEmu/Cmder, Windows OpenSSH (built-in). - Known problems by conhost type: - Built-in: crash when switching fullscreen -> regular or using `Ctrl+G` from fullscreen (#9186, microsoft/terminal#17515). - Built-in behind another terminal (mintty, OpenSSH): query replies leak into the prompt, BEL opens the external editor (#10256, #10362, #10742). - Old bundled (WezTerm 20240203): reply fragments in the prompt (#10717, #10970). - Built-in, classic console: reported regular-mode redraw issue (#6300). - Notes that the fixes exist upstream and reach the built-in conhost with a future Windows update, timing unknown. Sources: VS Code defaults `terminal.integrated.windowsUseConptyDll` to `true` (bundled conpty v1.25). Alacritty loads `conpty.dll` only if present (`alacritty_terminal/src/tty/windows/conpty.rs`) and its installer ships only `alacritty.exe`. The crash was verified locally in the classic console window on conhost 10.0.26100.9807: fullscreen -> regular crashed 3/3 runs and `Ctrl+G` from fullscreen crashed 2/2 runs (`0xC0000005`).
106 lines
5.9 KiB
Markdown
106 lines
5.9 KiB
Markdown
# Run Pi on Windows
|
|
|
|
Run Pi either as a native Windows process or inside Windows Subsystem for Linux (WSL). Native Windows uses Git Bash by default for Bash commands and can optionally expose PowerShell to the model. Pi inside WSL uses the Linux environment and its Bash installation.
|
|
|
|
Follow the main [Quickstart](quickstart.md) to install and authenticate Pi. Use this page to choose and configure its command environment.
|
|
|
|
## Choose native Windows or WSL
|
|
|
|
| Environment | Command environment | Use it when |
|
|
|---|---|---|
|
|
| Native Windows with Git Bash | Git Bash for the built-in `bash` tool and `!` commands | Your files and development tools primarily live on Windows |
|
|
| Native Windows with the `powershell` tool | PowerShell for model tool calls; Bash remains available for `!` commands | The task depends on PowerShell modules or Windows-native commands |
|
|
| WSL | Linux Bash and tools inside the selected WSL distribution | Your files and toolchain already live in Linux or WSL |
|
|
|
|
## Use Git Bash on native Windows
|
|
|
|
For most native Windows users, installing [Git for Windows](https://git-scm.com/download/win) is sufficient.
|
|
|
|
Pi resolves Bash in this order:
|
|
|
|
1. `shellPath` from `~/.pi/agent/settings.json`
|
|
2. Git Bash at `%ProgramFiles%\Git\bin\bash.exe`
|
|
3. Git Bash at `%ProgramFiles(x86)%\Git\bin\bash.exe`
|
|
4. `bash.exe` on `PATH`, including Cygwin, MSYS2, or legacy WSL Bash
|
|
|
|
Start Pi and enter this command to verify the shell:
|
|
|
|
```text
|
|
!printf 'Bash is working\n'
|
|
```
|
|
|
|
If Pi cannot find Bash, it reports the locations it checked. Install Git for Windows, put another Bash executable on `PATH`, or configure `shellPath`.
|
|
|
|
## Let the model use PowerShell
|
|
|
|
The optional `powershell` tool runs commands through `pwsh.exe` when available, then falls back to Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
|
|
|
|
PowerShell discovery checks these locations in order:
|
|
|
|
1. `pwsh.exe` on `PATH`
|
|
2. `%ProgramFiles%\PowerShell\7\pwsh.exe`
|
|
3. `powershell.exe` on `PATH`
|
|
4. `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`
|
|
|
|
To replace the model-facing `bash` tool with `powershell`, add this to `~/.pi/agent/settings.json`:
|
|
|
|
```json
|
|
{
|
|
"defaultTools": ["read", "powershell", "edit", "write"]
|
|
}
|
|
```
|
|
|
|
`["-bash", "+powershell"]` does the same while keeping any other default tools you configured.
|
|
|
|
Restart Pi, then ask it to run a harmless PowerShell command. The `!` and `!!` editor commands continue to use Bash. The `powershell` tool is available only when Pi runs as a native Windows process.
|
|
|
|
See [Settings](settings.md#tools) for other tool combinations.
|
|
|
|
## WSL
|
|
|
|
WSL path conversion on Windows and extra Git branch polling in WSL recognize `/mnt/<drive>`, not custom mount roots.
|
|
|
|
When using the legacy WSL `bash.exe` launcher from Windows, Pi sends commands over stdin to avoid command-line quoting problems.
|
|
|
|
## Use a custom Bash executable
|
|
|
|
Set `shellPath` when Bash is installed somewhere Pi does not discover automatically:
|
|
|
|
```json
|
|
{
|
|
"shellPath": "C:\\cygwin64\\bin\\bash.exe"
|
|
}
|
|
```
|
|
|
|
JSON uses backslashes for escape sequences. When you write a Windows path with backslashes, write each backslash twice, as shown above.
|
|
|
|
See [Configure shell commands](shell-aliases.md) for command prefixes, aliases, and the complete shell-resolution behavior.
|
|
|
|
## Choose a terminal
|
|
|
|
Windows terminals run Pi through a console host (conhost). Some bundle an up-to-date copy; others use the older one built into Windows, which has bugs that affect Pi.
|
|
|
|
We recommend [Windows Terminal](https://aka.ms/terminal). It always ships an up-to-date conhost, and Pi is best tested with it.
|
|
|
|
Last updated: October 2026.
|
|
|
|
| Terminal | Conhost | Status |
|
|
|---|---|---|
|
|
| [Windows Terminal](https://aka.ms/terminal) | Bundled, current | Recommended |
|
|
| [VS Code](https://code.visualstudio.com), [Tabby](https://tabby.sh), [WezTerm](https://wezterm.org) nightly | Bundled, current | Works |
|
|
| [Alacritty](https://alacritty.org) | Built-in, unless `conpty.dll` and `OpenConsole.exe` from Windows Terminal are next to `alacritty.exe` | Works only with those files |
|
|
| WezTerm 20240203 and older | Bundled, old | Known problems |
|
|
| Classic console (`cmd.exe` or PowerShell without Windows Terminal), mintty (Git Bash), ConEmu, Cmder, [Hyper](https://hyper.is), Windows OpenSSH | Built-in | Known problems |
|
|
|
|
| Problem | Where | Why |
|
|
|---|---|---|
|
|
| Switching from fullscreen to regular mode, or `Ctrl+G` from fullscreen, crashes the session ([#9186](https://github.com/earendil-works/pi/issues/9186), [microsoft/terminal#17515](https://github.com/microsoft/terminal/issues/17515)). Start with `--tui-mode regular` to avoid it. | Built-in | Conhost crashes when leaving the alternate screen while input is in line mode. |
|
|
| Text such as `;0;rgb:0000/0000/0000` appears in the prompt and BEL opens the external editor ([#10256](https://github.com/earendil-works/pi/issues/10256), [#10362](https://github.com/earendil-works/pi/issues/10362), [#10742](https://github.com/earendil-works/pi/issues/10742)) | Built-in behind another terminal (mintty, OpenSSH) | Conhost drops the start of terminal replies that arrive in pieces. |
|
|
| Fragments such as `79` or `55` appear in the prompt ([#10717](https://github.com/earendil-works/pi/issues/10717), [#10970](https://github.com/earendil-works/pi/issues/10970)) | WezTerm 20240203 | The bundled conhost cuts terminal replies short. |
|
|
| In regular mode, each keystroke redraws the input line on a new row ([#6300](https://github.com/earendil-works/pi/issues/6300)) | Built-in, classic console | Suspected: cursor wraps after full-width lines. |
|
|
|
|
Microsoft has fixed these bugs in its source, but has not said when the built-in conhost will get the fixes.
|
|
|
|
## Configure Windows Terminal
|
|
|
|
Windows Terminal reserves or rewrites some modified keys. See [Windows Terminal](terminal-setup.md#windows-terminal) to configure `Shift+Enter` and `Alt+Enter`, and [Keybindings](keybindings.md) for Pi's Windows and WSL shortcut defaults.
|