---
title: Windows beta
description: Native Windows support status, supported workflows, and known limitations.
---

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
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:

```toml
[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.

Preview packages include Microsoft's current app-local ConPTY runtime because the system ConPTY on older Windows 10 builds drops Kitty keyboard protocol sequences used by agents such as Kimi and Pi. Set `HERDR_WINDOWS_CONPTY=system` before starting Herdr only when diagnosing a compatibility problem with the bundled runtime.

## 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:

```powershell
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.
