Windows paths and migration

Blue uses native Windows Known Folders. Redirected profiles and organization-managed Known Folder locations are supported; Blue does not assume they are beneath %USERPROFILE%. An explicit XDG_CONFIG_HOME replaces the %APPDATA% parent for Blue configuration. An explicit XDG_CACHE_HOME replaces the cache parent. Blue still keeps machine-local runtime state beneath the Local AppData Known Folder. The PowerShell installer does not change your persistent PATH. Add %LOCALAPPDATA%\Blue\bin to your user PATH, then open a new terminal. Run blue doctor to see the resolved shim directory, its PATH position, and the upstream harness executables Blue detects.

​

How Blue finds and starts an agent

Blue resolves each agent the way cmd.exe does: it tries the bare name against every PATHEXT extension in turn. An npm global install writes three files — codex, codex.cmd, and codex.ps1 — and only the .cmd is something Windows can execute, so that is the one Blue detects and runs. Blue starts a .cmd wrapper through the command interpreter, the same way npm and node do. One consequence: an argument the interpreter would act on rather than forward — one containing %, &, |, <, >, ^, (, or ) — is refused instead of being passed through altered. Spaces, quotes, and backslashes are unaffected. Give such an argument inside the agent, or install a native build of it.

​

Relocate legacy state

Windows releases using the native layout do not read or automatically migrate %USERPROFILE%\.config\blue. If blue setup or blue doctor reports legacy state, close every Blue and coding-agent process before relocating files.

1. Move blue.toml, blue.yaml, session.json, mcp.json, and identities to %APPDATA%\Blue.
2. Move runtime, packages, package-state, package-state.json, .blue-transactions, locks, applied-state.json, merge-approvals.json, and session capture directories to %LOCALAPPDATA%\Blue\Data.
3. Move governance-config.json to %LOCALAPPDATA%\Blue\Cache.
4. Run blue doctor, then blue apply and blue verify.