[Windows] [sink-thread] How do you use Pi on windows? What issues are you seeing?

[petrroll]

Motivation

There are gazzilion developers on windows. Some use pi. Many could use pi. There are however too many ways pi can be run on windows and as such it is hard to know where to focus energy (fixing bugs, having best docs, having out of box) vs what ways can be delegated out of core to extensions.

Ways to run pi on WIndows:

• Pi runs on windows, uses git bash (default)
• Pi runs on windows, uses wsl bash (?semi-automatic fallback)
• Pi runs fully on windows with pwsh.exe/powershell.exe bash replacement (only plugins?)
• Pi runs fully in wsl2

Issues seen:

All of these have some papercuts. Windows/wsl bash suffers from #7064, Windows/* suffers from #7427, Windows/git-bash suffers from git bash being iffy and e.g. #6817 (among some closed). Full wsl2 has least amount of problems but might not be feasible due to compliance + still pi uses wrong keybidnings for copy/paste images with WT/allactitty. Running fully natively on windows/powershell isn't easy even with plugins as bash tool cannot be easily replaced (just shadowed; ie same name) and not all shell invocations can be hooked (RPC, ...).

Call to action:

As such, I'd like to ask: how do you use pi on windows? Why this particular way and not any of other of the abovementioned ones? If you use some plugins, why and which ones? What's missing? What's challenging? What UX gaps are you seeing?

Feel free to also link your other more specific issues.

[airtonix]

I prefer to use pi on linux any machine I'm allowed to... At work though... I am a hostage on windows, and have chosen it out of disgust for macosx.

So my main workflow is to live in wsl2 for as long as I can. If i could launch a wsl2 wayland desktop environment that was capable of covering all windows monitors then i'd be running everything else there too.

...

My main wishlist thing for pi on windows is largely about how the inevitable and already massive deluge of electron/electrobun/tauri wrappers that don't provide a ssh transport bus.

I can only assume they're all waiting for the "server mode" that splits pi into server/client architecture.

And I can only assume that the reason this hasn't come sooner is because smarter people than me (most people) are trying to work out how to do this split whilst also providing a way to communicate pi extensions that customise the TUI.

I really just want to be able to recommend pi desktop apps that can connect-to/start pi on other/multiple remote machines

[luminary19]

Thanks for making this.

The laptops that I've used has always been Windows. My Pi setup is, then, Pi runs fully on windows with pwsh.exe/powershell.exe bash replacement. Not sure what you meant by only plugins? though, could you clarify on this @petrroll .

Git Bash is, terrible. WSL bash mangles paths very often. Powershell is decent from my experience, but likely only because the other options are terrible? Which, then, leads to multiple rounds of patches and fixes to ensure that tool calls do not get bombarded out of orbit by errors. A long, terrible, very ad-hoc process (that eventually accumulates in SYSTEM.md, AGENTS.md rules) that I would not recommend to other Pi-on-Windows users. Not sure how this observation can translate to an actionable fix, maybe a SYSTEM.md starter template that is Windows-specific to avoid initial friction?

Additionally, a lot of extensions that are available out there need specific Windows reconfiguration, mainly because of UTF-8 decoding degradations. Again, this is not really Pi's fault, but having some pre-built guardrails on how Pi creates extensions (so that it works in Windows) and their Windows compliancy would help Windows users get integrated into the ecosystem.

A lot of vague thoughts, sorry. Truly a Windows birthright skill issue lol.

EDIT: On one concrete thought, the fact that LLMs create NUL artifacts seems to only happen on Windows. Can something be changed in Pi core to deterministically prohibit that?

[petrroll]

I myself use pi in wsl2 fully but for work (if I could, can't, locked to ghc cli) I'd rather go with native windows/pwsh.exe as I really like windows tools (vs, ...) so staying in windows land is preferrable.

It would be possible with windows/wsl2-bash but then you pay quite a bit for fs projection perf.

[petrroll]

@luminary19

Not sure what you meant by only plugins? though, could you clarify on this @petrroll

Well by default pi doesn't have any tool that'd call powershell.exe / pwsh.exe, no? it default to whatever bash it can find (git bash, wsl2 bash). There are some plugins to add pwsh/powershell but they usually do way more (background agents) and still have gaps (doesn't completely replace bash tool).

Additionally, a lot of extensions that are available out there need specific Windows reconfiguration, mainly because of UTF-8 decoding degradations

I'm surprised, windows pty supports full utf8 and I haven't had any problems. The app needs to ask for utf8 pipes etc. but other than that it should be fully working :).

I don't think pi would want to explicitely filter out NUL(s) but I wonder if with more explicit powershell.exe tool / one line 'youre using powershell' most good models wouldn't have problems. E.g. not sure what magic ghc cli does but I haven't had any problems with it using pwsh in months.

[mitsuhiko]

For the path handling I have considered adding this in the path to the system prompt:

File tools need native paths. You can convert Git Bash/MSYS paths like /c/foo with cygpath -w; do not pass /c/foo.

I wonder if people could test putting that into their APPEND_SYSTEM.md and see if that does anything good for them.

[DreamFate]

Embedding pi as a library inside an Electron app — we recently migrated the agent runtime from @anthropic-ai/claude-agent-sdk to pi. We don't use pi via the CLI at all.

How we run pi on Windows

• Agent from @earendil-works/pi-agent-core runs in the Electron main process; each conversation gets its own agent, we subscribe to the loop for streaming UI.
• Tools: harness built-ins (Read / Write / Edit / Bash) + our own (ToolDef → toPiTools). We wrap the harness ExecutionEnv to enforce workspace boundaries; shell exec is whatever pi's NodeExecutionEnv picks on Windows.
• Skills use the standard .claude/skills/<name>/SKILL.md layout.
• Profiles support both anthropic-messages and openai-responses wire formats (one of the main reasons we left the SDK).

Why this way (and not CLI / WSL / git-bash-swapped)

We came from the Claude Agent SDK, where we already had our own permission cards, interrupt queue, sub-session dispatch, and tool registry on top of query(). The CLI / coding-agent layer overlaps with what we'd built — staying at the library boundary (Agent.subscribe + custom tools + custom ExecutionEnv) is the natural fit for our migration shape. Running the agent runtime in the same Electron main process (rather than WSL) keeps the process model unified.

Plugins

None. We don't use pi-coding-agent either — its assumptions conflict with our conversation/group/workspace model.

Issues seen / what's challenging

• Windows: loadSkills throws RangeError from ignore lib on recursive skill dirs #7427 is the only hard blocker we've hit. Skill discovery crashed at startup on Windows until we patched; flat layout hides it, only recursive scan triggers — easy to miss.
• The path-normalization pattern repeats across harness files (skills.ts, env/nodejs.ts, prompt-templates.ts). A single posixPath() helper + a sweep would prevent the next regression from popping up somewhere else.
• We don't really hit WSL absolute windows paths are mishandled #7064 / find returns no results for path patterns like src/**/*.ts on Windows #6817 in normal usage — most Bash invocations in our app are light (git status, file inspection). Heavier shell users would feel those more.

What's missing / UX gaps

• A documented "embedded library" entry point. Most docs assume CLI; a quickstart for Agent.subscribe + custom tools + custom ExecutionEnv would lower the bar.
• Windows in CI — even a loadSkills smoke test on Windows runners would have caught Windows: loadSkills throws RangeError from ignore lib on recursive skill dirs #7427 before release.

[luminary19]

Well by default pi doesn't have any tool that'd call powershell.exe / pwsh.exe, no? it default to whatever bash it can find (git bash, wsl2 bash). There are some plugins to add pwsh/powershell but they usually do way more (background agents) and still have gaps (doesn't completely replace bash tool).

Hmm, I can't say for sure? I prohibited regular bash calls both in the SYSTEM.md and deterministically, which results to my Pi calling Powershell straight up as replacement even in pi -ne. I haven't used any plugins for it so I can't say I share the same errors.

I'm surprised, windows pty supports full utf8 and I haven't had any problems. The app needs to ask for utf8 pipes etc. but other than that it should be fully working :).

Haha I mean, yeah it's supported, but the explicit ask for UTF8 pipes itself is the part most exts (at least the ones I installed previously) didn't do. Can't recall exactly how many ports I did specifically because of that, but the majority of my exts (retry, to-do, langfuse, ext-mgr to name a few) needed to be ported to fit.

File tools need native paths. You can convert Git Bash/MSYS paths like /c/foo with cygpath -w; do not pass /c/foo.

Just out of curiosity @mitsuhiko , would a deterministic catcher over the system prompt be too restrictive here? I have a resolvePath function that I pass into tool calls that attempts to format the path before acting on it. Would probably need to A/B test to know the exact effect delta over system prompts, but this has felt quite decent so far.