Running on Windows
The itervox daemon runs natively on Windows 10 and 11 (x64 and Arm64, #259).
Claude Code and Codex both run on Windows, and Claude Code there uses Git
Bash, which also gives Itervox’s hooks the bash they are written for.
Install
Section titled “Install”-
Download
itervox_windows_amd64.zip(oritervox_windows_arm64.zipon an Arm PC) from the latest release. Homebrew is for macOS and Linux only. -
Unzip it and move
itervox.exeto a folder of its own, for example%LOCALAPPDATA%\Programs\itervox. -
Put that folder on your PATH: Settings → System → About → Advanced system settings → Environment Variables, select
Pathunder User variables, Edit → New, paste the folder, then open a new terminal. From PowerShell instead:Terminal window $dir = "$env:LOCALAPPDATA\Programs\itervox"[Environment]::SetEnvironmentVariable("Path", "$([Environment]::GetEnvironmentVariable('Path','User'));$dir", "User") -
Install Git for Windows. Itervox needs
gitfor worktrees, and Git Bash’sbash.exefor hooks. -
Check it:
itervox --version, thenitervox demo, which runs a board with a fake agent and needs no account, key or agent CLI.
Which shell runs what
Section titled “Which shell runs what”Hooks (hooks.*) are bash scripts, and an agent CLI given by name
(agent.command: claude) is started through a login shell so your profile’s
PATH applies, exactly as on Linux and macOS. On Windows, Itervox looks for
that bash in this order:
ITERVOX_SHELL— a full path to abash.exe;- Git for Windows’ bash,
%ProgramFiles%\Git\bin\bash.exe; bashon PATH — exceptC:\Windows\System32\bash.exe, the WSL launcher, whose bash runs inside Linux and cannot see your Windows tools.
When none is found:
- the agent CLI is executed directly (
agent.command: claude --model opusrunsclaudefrom your Windows PATH with those arguments); - every hook fails with
hook_failed: no bash to run hooks with: install Git for Windows (Git Bash) or set ITERVOX_SHELL to a bash.exe.
$SHELL is ignored on Windows: when it is set (Git Bash sets it) it holds an
MSYS path such as /usr/bin/bash, which Windows cannot start.
What differs on Windows
Section titled “What differs on Windows”| Area | On Windows |
|---|---|
| Stopping agents | Each agent and hook runs in a Windows Job Object. Cancelling a run ends its whole process tree, and if the daemon itself dies, Windows ends every agent it started. There is no orphan ledger (.itervox/run/agent-pgids.json) to reap after a crash. |
itervox stop | Ends the daemon at once: Windows has no SIGTERM to send to another process, so there is no graceful drain. Press Ctrl+C in the daemon’s own console to drain running agents first. |
| Prompt delivery | The prompt reaches a CLI started through Git Bash on that shell’s stdin (Windows cannot hand a child an extra file descriptor). A login profile that reads stdin would consume it; Git Bash’s default profile does not. |
| Guardrail shims | Each shim gets a .cmd wrapper next to it, so git and gh typed in cmd.exe or PowerShell are guarded too; Git Bash uses the shell shims. |
| Lock files | The pid lock, the WORKFLOW.md edit lock, the API-token store lock and the hub lock use Windows file locks; a killed daemon releases them at once, as on Unix. |
Not available on Windows
Section titled “Not available on Windows”- tmux control — tmux does not run on Windows. A workflow with
sessions.tmux_control: trueis refused when the daemon loads it, withsessions.tmux_control: true is not available on Windows. New session in the Sessions panel reports tmux as unavailable. - Whether a hand-started session is still running — the Sessions panel
decides this from
/procorpsandlsof, which Windows lacks; the check reportsprocess inspection is not available on Windows. - The login-shell PATH lookup (Login-shell PATH) — the daemon keeps the PATH it was started with.
- Changing a file’s owner in
itervox secretwhen run as root — Windows has no Unix owners.
Desktop app
Section titled “Desktop app”The Windows desktop app is tracked separately; this page covers the command-line daemon it runs.