Windows Setup

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 20+

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+ (20+ recommended); OpenCode and Pi work on 18+. Installing Node 20 LTS covers everything except Codex — upgrade to Node 22 if you need Codex.

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 — including Codemux itself if it was open during the install.

This is a Windows quirk: installers update PATH via HKCU\Environment\PATH and broadcast WM_SETTINGCHANGE, but already-running processes may miss the broadcast. A new PowerShell window launched from Explorer sees the updated PATH; Codemux may not.

Codemux handles this automatically — it checks %USERPROFILE%\.local\bin directly as a fallback, and the shell spawned inside each terminal pane has .local\bin prepended to its PATH on every launch. In practice you should not need to do anything special.

If you still see "Claude Code is not installed" after installing, the fastest fix is to close Codemux completely and relaunch it. A fresh process always gets the fresh PATH.

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.

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

OpenFlow is disabled on Windows

OpenFlow (multi-agent orchestration) relies on bash wrapper scripts that don't have a PowerShell equivalent yet. On Windows the sidebar shows a greyed-out "OpenFlow is not yet available on Windows" tooltip.

Individual agent presets (Claude Code, Codex, Gemini, OpenCode, Pi) all launch normally as terminal sessions. Only the multi-agent orchestration layer is offline.

OS-level input injection is not 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 SendInput for bypassing anti-bot detection) is not yet implemented. In practice Tiers 1 and 2 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's environment probably has a stale PATH from before you installed Claude Code. Fix:

1. Close Codemux entirely (not just the window — wait for the process to exit).
2. Reopen Codemux from the Start Menu.
3. Click the Claude Code preset again.

If that doesn't work, verify the install location:

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

If it returns False, rerun irm https://claude.ai/install.ps1 | iex.

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.

"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