Windows beta

Preview docs describe unreleased preview builds. Stable docs remain at /docs/.

Native Windows support is experimental beta.

Herdr on Windows uses ConPTY and Windows process/runtime behavior instead of the Unix PTY model Herdr was originally built around. Some Herdr features map cleanly to Windows, and some do not. This preview is not a commitment that every Linux/macOS feature will become fully supported on Windows.

The goal of the beta is to learn from real use: install success, pane reliability, agent workflows, bug volume, missing features, and whether Windows users are getting enough value from Herdr. Based on that feedback, Windows support may graduate to stable, stay preview-only while it matures, or be reduced if the maintenance cost is not justified.

Install native Windows beta builds with PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

Windows beta builds ship only through the preview channel. Herdr defaults to preview on Windows without changing your config. The installer stores releases under %USERPROFILE%\.herdr\packages\standalone\releases, points %LOCALAPPDATA%\Programs\Herdr\bin at the current release, and keeps a small number of older releases so running processes do not block updates.

For internal beta testing, HERDR_MANIFEST_URL can point the installer at a custom manifest instead of Herdr’s stable or preview manifest.

Supported in beta

Capability	Status
Local persistent sessions	beta
Native panes through ConPTY	beta
Windows Terminal / PowerShell app attach	beta
cmd.exe panes	beta
Startup cwd and workspace labels	beta
Pane launch cwd	beta
Agent command discovery	beta
Agent self-report integrations	beta
Agent process-tree detection	beta
Git/worktree detection from known cwd	beta
Plugins	preview
Pane screen history	beta
Nested launch override	beta

Windows agent process detection scans descendants of the pane shell and recognizes direct agents plus common command wrappers. It is useful for Codex, Claude, and similar agents, but it is not the same as Unix foreground process-group detection.

Plugins support windows as a manifest platform in preview. GitHub install, local link, build commands, actions, events, and plugin panes are best effort on Windows. Commands are argv commands and must be Windows-compatible; Node package shims such as npm, bun, and node are expected to work when they are on PATH, while Unix-only examples using sh or Bash need Windows-specific alternatives. Platform filters skip unsupported build commands and return platform_unsupported for unsupported actions or panes.

Partial support

Capability	Status
Live cwd after shell cd	partial
Live cwd via shell integration/OSC7	beta
Clipboard image paste to agents	unverified
CJK IME composition anchoring	partial
Kitty graphics rendering	unverified
Host cursor rendering	partial

Herdr can launch panes in the right directory and can create the initial workspace from the directory where you started Herdr. PowerShell directory changes after startup are different: the process field Herdr can inspect does not reliably track later logical cd changes. Use Herdr integrations or prompt shell integration for live cwd reporting.

Windows Terminal may support image paste paths for specific agents, but Herdr’s own clipboard-image reader is not wired on Windows yet. Treat alt+v image paste as unverified until the Windows clipboard bridge is implemented and tested. Remote clipboard image bridging is separate and remains tied to Unix/macOS herdr --remote.

Kitty graphics remains experimental and is not claimed as Windows-supported yet. Leave experimental.kitty_graphics = false unless you are specifically testing image rendering in Windows Terminal.

Known caveats

Cursor rendering

Herdr relies on ConPTY for native Windows panes. The current Windows terminal cursor path can expose intermediate cursor positions while a multiplexer repaints the screen. A native cursor may flicker, jump, or briefly remain at an old position during active output. This behavior also reproduces in other native Windows terminal multiplexers and with direct VT cursor-position stress tests, so Herdr cannot eliminate it while preserving native cursor behavior.

To prioritize visual stability, the default host_cursor = "auto" draws Herdr’s cursor as terminal cell content on native Windows and WSL. Other Linux and macOS clients continue to use the native terminal cursor. The drawn Windows cursor is steady and non-blinking, but it does not provide the outer terminal’s native blink, shape, or cursor color.

A drawn cursor is not the cursor that Windows uses to position IME composition and candidate UI. Korean, Japanese, or Chinese IME UI may therefore appear at the wrong location. If this affects you, opt back into the outer terminal cursor:

[ui]
host_cursor = "native"

Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output. This is currently a compatibility trade-off in the Windows beta.

Keyboard and mouse

Windows terminals do not all report modified keys in the same shape. Herdr preserves mouse reporting and ctrl+j in Windows Terminal and Alacritty on Windows, but shift+enter only works when the outer terminal reports it as a distinct modified Enter key. If Windows or the terminal reports it as plain Enter, Herdr forwards plain Enter.

Copy and paste

Herdr’s pane text copy works on Windows beta. Drag-select text inside a pane to copy through Herdr.

For text paste, use ctrl+shift+v in Windows Terminal. Multiline text paste is bracketed so shells and agent prompts receive it as one paste instead of submitting each line separately. Hold shift and right-click to use the outer terminal paste action instead of sending the click through Herdr.

Not supported on Windows beta

Capability	Status
Direct terminal attach	unsupported
herdr --remote from the Windows binary	unsupported
Live server handoff	unsupported
Unix file-descriptor handoff	unsupported
Unix foreground process groups	unsupported
Remote clipboard image bridge	unsupported
Prefix input-source switching	unsupported
Signed binary / SmartScreen avoidance	unsupported

For remote work from Windows, SSH into the server and run herdr there:

ssh you@server
herdr

That mode runs Herdr on the remote host. Native Windows herdr --remote is not part of the beta.

Windows updates run through the Windows installer and update the versioned install junction. Restart running Herdr sessions after updating. Live handoff is Unix-only.

Reporting Windows beta issues

Include:

• Herdr version.
• Windows version.
• Terminal app.
• Shell, such as PowerShell or cmd.
• Whether you used a named HERDR_SESSION.
• Relevant Herdr logs.
• Exact steps to reproduce.