Skip to main content
CODEMUXManual

Windows Setup

Install and run Codemux on Windows 10+ with Claude Code and the other agent CLIs.

Codemux runs natively on Windows 10 1809+, Windows 11, and Windows Server 2016+. This guide walks through prerequisites, agent CLI installation, and common troubleshooting. Windows x86_64 is supported; Windows ARM64 is not yet (see Known Limitations).

For Linux build instructions, see Installation.

Prerequisites

Git for Windows

Codemux uses Git for worktrees, diffs, and branch handling. Claude Code additionally shells out to Git Bash internally, so Git for Windows must be installed even if you don't use Git directly.

winget install --id Git.Git -e --source winget

Verify:

git --version

Node.js 22+

Claude Code is the only agent CLI that doesn't need Node.js — it ships as a native installer. Codex, Gemini, OpenCode, and Pi all install via npm i -g, so Node.js is required for anything other than Claude Code.

winget install --id OpenJS.NodeJS.LTS -e --source winget

Note: Codex requires Node 22+; Gemini requires 18+; OpenCode and Pi work on 18+. Installing Node 22 LTS covers every supported npm-installed agent.

PowerShell (no install needed)

Codemux defaults to PowerShell on Windows in this order:

  1. pwsh.exe — PowerShell 7+, preferred when installed
  2. powershell.exe — Windows PowerShell 5.1, pre-installed on every supported Windows version
  3. cmd.exe — last-resort fallback only

You don't need to install anything — Windows PowerShell 5.1 is always present. Install PowerShell 7 only if you want the newer language features; Codemux picks it up automatically.

winget install --id Microsoft.PowerShell -e --source winget

Why not cmd.exe: cmd.exe can't handle multi-line environment variables and doesn't support $env:VAR syntax. Agent presets will not work under cmd.exe. If you override your shell to cmd.exe, the agent receives a literal $env:CODEMUX_AGENT_CONTEXT string as its system prompt.

Installing Claude Code

The recommended Windows install is the native installer, which drops a standalone claude.exe at %USERPROFILE%\.local\bin\claude.exe and adds that directory to your user PATH.

Open PowerShell and run:

irm https://claude.ai/install.ps1 | iex

Alternative methods:

  • winget: winget install Anthropic.ClaudeCode
  • npm (deprecated): npm i -g @anthropic-ai/claude-code

Verify:

claude --version

The PATH propagation gotcha

After installing Claude Code, claude works in a freshly-opened terminal but may not work in a process that was already running. The native installers can also leave %USERPROFILE%\.local\bin off your PATH entirely.

This is a Windows quirk: installers update PATH via HKCU\Environment\PATH and broadcast WM_SETTINGCHANGE, but already-running processes may miss the broadcast, and no installer can change the environment of a process that's already running.

Codemux handles this automatically. At launch it puts %USERPROFILE%\.local\bin at the front of its own PATH — even if the directory doesn't exist yet — without changing your saved PATH. Agent detection, model discovery, chat sessions, and terminal panes all use it, so a native Claude install is found even when the installer left it off PATH, and Claude Code installed while Codemux is running is picked up without a restart.

If you still see "Claude Code is not installed", check that claude.exe actually landed in %USERPROFILE%\.local\bin (see Troubleshooting).

Installing Other Agent CLIs

All four additional agent CLIs install via npm with a single command. The npm global install directory (%APPDATA%\npm) is on your user PATH automatically when Node.js is installed via the official installer or winget.

Codex (OpenAI)

npm install -g @openai/codex

Requires Node 22+.

Alternative: download the prebuilt Rust binary from the Codex releases page, rename it to codex.exe, and drop it into %USERPROFILE%\.local\bin\.

Gemini CLI

npm install -g @google/gemini-cli

Requires Node 18+ (20+ recommended). Gemini reads system prompts from a file pointed to by GEMINI_SYSTEM_MD; Codemux writes the agent context to %TEMP%\codemux-<workspace>-gemini-system.md at preset launch and sets the env var automatically.

OpenCode

npm install -g opencode-ai@latest

Alternatives: scoop install opencode or choco install opencode.

Codemux supports both OpenCode 1.x and OpenCode 2. With an npm install, opencode on PATH is npm's launcher script rather than the program itself; Codemux reads the npm package layout (without running the launcher) to find the native opencode.exe and runs that directly. This covers the current npm layout and the older 1.14-era one, where the binary lives in a platform-specific optional dependency (opencode-windows-x64, opencode-windows-x64-baseline, or opencode-windows-arm64). The first opencode on your PATH wins.

If Codemux can't resolve the launcher — a damaged node_modules, or an unusual layout — it reports OpenCode as unavailable and explains why. Point it at the native executable instead by setting CODEMUX_OPENCODE_BINARY to the full path of opencode.exe; that override always takes precedence.

Note: OpenCode upstream recommends WSL on Windows. Native Windows installs work but have known rough edges. OpenCode has no system-prompt injection mechanism (same limitation on Linux), so Codemux's workspace context is not passed to OpenCode sessions — the agent runs without knowing it's inside a Codemux workspace.

Pi (pi-coding-agent)

npm install -g @mariozechner/pi-coding-agent

Heads up — naming collision: this is pi-mono by Mario Zechner, not Inflection AI's Pi chatbot. Source: github.com/badlogic/pi-mono.

Known Limitations

OS-level input injection is available

Codemux uses three input tiers for browser automation. Tier 1 (DOM-based) and Tier 2 (coordinate-based) both work on Windows. Tier 3 (OS-level input injection) is also implemented on Windows, via Win32 SendInput — os_input.rs's windows_impl module provides mouse/keyboard synthesis, a Bezier approach path, and click_os / type_os. In practice Tiers 1 and 2 still handle the vast majority of automation needs.

Unsigned installer / SmartScreen warning

The Windows installer is not code-signed yet. On first install, Windows SmartScreen will show a "Windows protected your PC" warning. Click More info → Run anyway. The installer is safe — it just doesn't carry an Authenticode signature.

The bundled browser automation binary (agent-browser-win32-x64.exe) is also a known Windows Defender false-positive. If Defender quarantines it, whitelist the Codemux install directory under Windows Security → Virus & threat protection → Exclusions.

Windows ARM64 is not supported

The browser automation dependency does not ship an ARM64 Windows binary. Surface Pro X and similar Windows ARM64 devices can't use the browser pane. Agent CLIs themselves work fine on ARM64, but the browser-automation flow is unavailable.

Troubleshooting

"Claude Code is not installed" on preset click

Codemux already looks in %USERPROFILE%\.local\bin, so first verify the install location:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

If it returns False, rerun irm https://claude.ai/install.ps1 | iex. If Claude Code is installed somewhere else (winget or npm), close Codemux completely and relaunch it so it picks up the updated PATH.

Agent launches but errors with "command not found"

The binary is probably installed to a non-standard location. Check where:

Get-Command claude

If the path is unusual, either move the binary to %USERPROFILE%\.local\bin\ or add your custom path to your user PATH via System Properties → Advanced → Environment Variables, then restart Codemux.

Agent receives a literal $env:CODEMUX_AGENT_CONTEXT string

You've overridden your default shell to something other than PowerShell. Codemux injects PowerShell-flavored env var expansion ($env:VAR), which only matches PowerShell syntax. Reset your shell to the default (PowerShell is auto-detected).

Windows Defender quarantines Codemux or agent-browser

Codemux is unsigned and agent-browser-win32-x64.exe is a known Defender false-positive. Fix:

  1. Open Windows Security → Virus & threat protection → Protection history.
  2. Find the quarantine event, click Actions → Restore.
  3. Add the Codemux install directory as an exclusion under Exclusions → Add an exclusion → Folder.
  4. Restart Codemux.

The window went blank or froze

The interface runs in its own WebView2 process; the backend, terminals, and agents keep running outside it. Press Ctrl+Alt+R to reload just the interface — it works even when the page won't respond. Once the window is flagged unresponsive, Ctrl+R and F5 do the same. If the window can't take keyboard input at all, run codemux reload-ui from any terminal. If the renderer crashes, Codemux reloads it automatically (up to 3 times a minute). Unsent chat text survives the reload.

"Node.js is not recognized" after installing it

Restart your terminal and Codemux. Node's installer adds directories to PATH that only propagate to newly-launched processes.

claude works in Windows Terminal but not in VS Code's integrated terminal

VS Code inherits a stale environment block from when it was launched. Restart VS Code entirely (not just the terminal pane) so it picks up the updated PATH.

Getting Help

If you hit a Windows-specific issue not covered here, file it at github.com/Zeus-Deus/codemux/issues/new with:

  • Your Windows version (winver)
  • Your Codemux version
  • Which agent CLI you're using
  • The exact error (screenshot or copy-paste)
  • Whether claude --version (or equivalent) works in a freshly-opened PowerShell window