Windows beta
Next docs describe unreleased work from
master. Stable docs remain at /docs/.
Native Windows support is experimental beta.
PK-Herdr on Windows uses ConPTY and Windows process/runtime behavior instead of the Unix PTY model PK-Herdr was originally built around. Some PK-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 PK-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.pkking.computer/install.ps1 | iex"Windows beta builds ship only through the preview channel. PK-Herdr defaults to preview on Windows without changing your config. The installer stores releases under %USERPROFILE%\.herdr\packages\standalone\releases, points %LOCALAPPDATA%\Programs\PK-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 PK-Herdr’s stable or preview manifest.
Supported in beta
Section titled “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 |
pk-herdr --remote thin client to Linux/macOS servers | beta (Windows OpenSSH Client; one fresh SSH connection per operation, no multiplexing in v1) |
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
Section titled “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 |
PK-Herdr can launch panes in the right directory and can create the initial workspace from the directory where you started PK-Herdr. PowerShell directory changes after startup are different: the process field PK-Herdr can inspect does not reliably track later logical cd changes. Use PK-Herdr integrations or prompt shell integration for live cwd reporting.
Windows Terminal may support image paste paths for specific agents, but PK-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 pk-herdr --remote until the Windows clipboard reader is wired.
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
Section titled “Known caveats”Cursor rendering
Section titled “Cursor rendering”PK-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 PK-Herdr cannot eliminate it while preserving native cursor behavior.
To prioritize visual stability, the default host_cursor = "auto" draws PK-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
Section titled “Keyboard and mouse”Windows terminals do not all report modified keys in the same shape. PK-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, PK-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 PK-Herdr only when diagnosing a compatibility problem with the bundled runtime.
Copy and paste
Section titled “Copy and paste”PK-Herdr’s pane text copy works on Windows beta. Drag-select text inside a pane to copy through PK-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 PK-Herdr.
Not supported on Windows beta
Section titled “Not supported on Windows beta”| Capability | Status |
|---|---|
| Direct terminal attach | 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, either thin-attach with pk-herdr --remote <target> (requires the Windows OpenSSH Client, ssh.exe), or SSH into the server and run pk-herdr there:
ssh you@serverpk-herdrThat second mode runs PK-Herdr on the remote host. Native Windows pk-herdr --remote attaches to remote Linux and macOS servers; the remote side is never a Windows host.
Windows updates run through the Windows installer and update the versioned install junction. Restart running PK-Herdr sessions after updating. Live handoff is Unix-only.
Reporting Windows beta issues
Section titled “Reporting Windows beta issues”Include:
- PK-Herdr version.
- Windows version.
- Terminal app.
- Shell, such as PowerShell or cmd.
- Whether you used a named
HERDR_SESSION. - Relevant PK-Herdr logs.
- Exact steps to reproduce.