25cc5c7bf4
* docs(coding-agent): improve getting started documentation * docs(coding-agent): correct getting started details * docs(coding-agent): clarify SDK entry point * docs(coding-agent): restructure guides and references * docs(coding-agent): improve getting started guides * docs(coding-agent): refresh integration guides * docs(coding-agent): improve terminal and CLI guides * docs(coding-agent): refresh customisation guides * docs(coding-agent): clarify project trust terminology * docs(coding-agent): simplify customisation guidance * docs(coding-agent): improve runtime and reference guidance * Fix settings reference * feat(coding-agent): add Crowdin documentation sync * docs(coding-agent): separate CLI and slash command references * docs(coding-agent): correct compaction reference * docs(coding-agent): streamline package documentation * docs(coding-agent): split RPC reference documentation * Update configuration docs * Shorten config docs * docs(coding-agent): refine configuration references * docs(coding-agent): streamline settings reference * docs(coding-agent): clarify configuration reference * docs(coding-agent): clarify project trust exception * docs(coding-agent): simplify keybindings reference * docs(coding-agent): remove Crowdin integration * docs(coding-agent): turn themes reference into guide * docs(coding-agent): consolidate model and authentication docs * docs(tui): require Component.invalidate() (fixes #9358) * docs(coding-agent): document offline catalog behavior (fixes #8684) * docs(coding-agent): preserve established documentation routes * docs(coding-agent): reorganize documentation navigation * docs(coding-agent): correct audited behavior Clarify provider, session, local-model, Termux, TUI, SDK, debug, and extension behavior. Simplify the documentation audit to report only clear user-visible contradictions. * docs(coding-agent): fix broken documentation links
3 KiB
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 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 is sufficient.
Pi resolves Bash in this order:
shellPathfrom~/.pi/agent/settings.json- Git Bash under
Program FilesorProgram Files (x86) bash.exeonPATH, including Cygwin, MSYS2, or legacy WSL Bash
Start Pi and enter this command to verify the shell:
!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.
To replace the model-facing bash tool with powershell, add this to ~/.pi/agent/settings.json:
{
"defaultTools": ["read", "powershell", "edit", "write"]
}
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 for other tool combinations.
Use a custom Bash executable
Set shellPath when Bash is installed somewhere Pi does not discover automatically:
{
"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 for command prefixes, aliases, and the complete shell-resolution behavior.
Configure Windows Terminal
Windows Terminal reserves or rewrites some modified keys. See Windows Terminal to configure Shift+Enter and Alt+Enter, and Keybindings for Pi's Windows and WSL shortcut defaults.