winget install --id=hdosys.herdr-win -e An unofficial, upstream-first Windows distribution of Herdr built from the latest reviewed stable Herdr release plus a small, reviewable Windows patch queue. The executable and command remain herdr.
An upstream-friendly Herdr distribution for developers who need extended capabilities today: multi-agent extensions, terminal experience improvements, better OpenCode integration, and first-class Windows support.
Despite its historical name, herdr-win is not Windows-only. It is an unofficial, upstream-first extended distribution that makes practical bug fixes and extensions available today through a small, reviewable patch queue designed for upstream adoption. Its strongest focus areas are multi-agent workflows, terminal experience, OpenCode reliability, and Windows support. It complements upstream Herdr while the executable, command, configuration, state, sessions, sockets, and protocol remain herdr.
Every published release contains matching Windows, Linux, and macOS binaries built from one reviewed stable Herdr release and one ordered patch queue. Releases are normal stable GitHub releases, and the integrated update paths reject prerelease feeds.
> [!IMPORTANT]
> GitHub's ahead/behind banner compares commit ancestry, not release-source freshness. This repository's master is a control branch for the patch queue and release automation, not a mirror of upstream master. Each build starts from the stable commit recorded in BASE and applies the maintained patches. GitHub's Sync fork action is not this project's refresh mechanism.
> [!NOTE] > herdr-win is developed and validated with Herdr Sandbox, a sister project that provides disposable native Windows environments for coding agents. It is not a runtime dependency.
What differs from upstream · Install · First use · Everyday use · Troubleshooting · Project reference
https://github.com/user-attachments/assets/b6c02367-683b-4a1f-94e6-b662149d89d9
Detach from a Windows-hosted Herdr session, reconnect from another terminal, and continue the same OpenCode session without RDP.
flowchart TB
S["Reviewed stable sourceUpstream Herdr v0.9.0 / BASE b99002ac99b0"]
Q["Control branch: patches/delta/series0001 Terminal experience / 0003 Windows SSH / 0004 Managed distribution0005 OpenCode / 0006 Downloads / 0008 Worktree lifecycle0009 Agent start / 0010 Hook recovery / 0011 Metadata0012 Completion / 0013 History / 0015 Contrast / 0016 Integration hints"]
B["Corrections after the foundation0019-0027, 0030 Reviewed upstream backports0028-0029, 0031 Local fixes and discoverability"]
D["Current maintained sourceFinalized queue reproduces the accepted source tree"]
V["Validated distributionFresh replay → native + cross-platform gates→ Windows setup + ZIP, Linux/macOS binaries + digests"]
S --> Q --> B --> D --> V
patches/delta/BASE records the exact reviewed upstream stable commit. series is the only patch order. A manual build replays that source and retains one complete candidate; promotion publishes those exact bytes without rebuilding or repackaging them.
The table is intentionally capability-level. ✅ marks capabilities now provided by upstream. The linked mailboxes contain the exact implementation and focused evidence for behavior still maintained here.
| Area | Status | What this repository contributes |
|---|---|---|
| Native ConPTY foundation | ✅ Upstreamed in Herdr v0.6.9 | Reuses Herdr's modern app-local ConPTY packaging instead of carrying a duplicate foundation. |
| Terminal experience | Maintained here · 0001 | Follows host light/dark appearance, preserves cursor and Windows VTI input behavior, and avoids unframed OSC 4 palette replies. |
| Windows SSH target support | Maintained here · #2329 · 0003 | Adds x86_64/ARM64 host detection, exact provisioning and activation, visible interactive progress, and fail-closed detached launch into the SSH user's active desktop session. |
| Managed Windows releases | Maintained here · 0004 | Provides per-user setup, portable archives, immutable runtime activation, update ownership, process-safe uninstall, and stable-only release selection. |
| OpenCode and multi-Agent workflows | Maintained here · #3052 · #2450 · 0005 | Keeps retries and prompts truthful, preserves each pane's selected root session, and maps concurrent direct subagents from managed OpenCode roots into adaptive readable splits. |
| Runtime downloads | Maintained here · 0006 | Ignores user curl configuration and bounds runtime downloads to TLS 1.2+ HTTPS with limited redirects. |
| Cross-platform docs checks | ✅ Upstreamed in Herdr v0.9.0 · #3041 | Upstream's documentation-parity assertion now uses native path separators on Windows and POSIX systems. |
| Worktree lifecycle | Maintained here · #3044 · 0008 | Scopes Git trust to the selected checkout, waits for Windows terminals before unregistering worktrees, and preserves foreground focus during background removal. |
| Managed Agent start | Maintained here · #321 · #2685 · 0009 | Optionally starts one Agent in each new tab, catches up eligible shell roots after live reload, and shares each selected shell's native command syntax with session restore. |
| Agent hook recovery | Maintained here · #1033 · 0010 | Lets a still-running full-lifecycle Agent regain hook authority after a temporary foreground takeover without reviving a session after a real exit. |
| Metadata capacity | Maintained here · 0011 | Atomically updates and retains up to 64 pane or workspace metadata tokens while preserving existing validation bounds. |
| Completion alerts | Maintained here · 0012 | Exposes one persistent opt-out for completion popups and sounds while keeping questions, permission prompts, and errors actionable. |
| Terminal history | Maintained here · #2893 · 0013 | Retains repeated rows that scroll into alternate-screen history. |
| Plugin command resolution | ✅ Upstreamed in Herdr v0.9.0 · #3024 | Upstream resolves explicit relative pane commands from the linked plugin root, including Windows plugin-local executables. |
| Muted-label contrast | Maintained here · #2692 · 0015 | Keeps muted sidebar and inactive tab labels readable. |
| Integration settings | Maintained here · #2880 · 0016 | Shows only controls that the selected integration supports. |
| Devin configuration | ✅ Upstreamed in Herdr v0.9.0 · #2724 | Upstream finds Devin's native configuration in roaming AppData while respecting an explicit XDG override. |
| Windows process environment | ✅ Upstreamed in Herdr v0.9.0 · #3430 | Upstream rejects malformed Windows environment entries and validates registry values before process creation. |
| Remote transport and input corrections | Included in v2026.09.10.1 · Inventory | Preserves Windows download and endpoint-write progress, matching control-key text, and nested mouse input. |
| Multi-machine workspace views | Included in v2026.09.10.1 · Inventory | Scopes collapsed groups to each machine, focuses new worktrees in the requesting client, supports guarded cross-machine navigation, and preserves public focus and focused geometry. |
| Session safety and startup diagnostics | Included in v2026.09.10.1 · Inventory | Requires exact recorded names for session deletion and keeps Local startup errors visible without freezing healthy remote views. |
These corrections are included in herdr-win v2026.09.10.1. They keep the reviewed v0.9.0 base unchanged. An upstream PR reference is provenance, not a claim that the fix has shipped in upstream stable; temporary mailboxes remain until equivalent stable behavior includes the necessary adaptations.
Every release provides Windows, Linux, and macOS builds as one coherent distribution. Choose one installation method for each machine:
Windows managed installations are per-user, require no administrator access, and need no separately installed Microsoft Visual C++ Redistributable. The Windows portable ZIP is a standalone alternative.
Install from the WinGet community source:
winget install --id hdosys.herdr-win --exact --source winget
Download herdr-win_v_windows_amd64_setup.exe from the latest Herdr Win release, verify its GitHub SHA-256 digest, and run it.
The managed install lives under %LOCALAPPDATA%\Programs\Herdr, registers Herdr Win in Installed Apps, installs Herdr's canonical agent skill, and preserves customized skill copies.
The Windows release also includes herdr-win_v_windows_amd64.zip. Extract the complete archive into one directory and run herdr.exe; keep its ConPTY payload beside it.
Linux and macOS releases are raw linux_amd64, linux_arm64, macos_amd64, and macos_arm64 executables. Clients negotiate endpoint generation and required codecs. Optional cursor-color support uses a named extension; exact provisioning still uses matching herdr-win release assets.
After downloading a Linux or macOS asset, mark it executable, rename it to herdr, and place it in a directory on PATH.
> [!WARNING] > The executable and setup are currently unsigned, so Windows may show a SmartScreen warning. Download only from this repository and verify the SHA-256 digest before running the artifact.
Open a new terminal after installation and run:
herdr --version
herdr
A published build reports herdr-win (Herdr ). The second command opens Herdr's normal keyboard-first terminal interface. General commands, configuration, keybindings, and integrations remain documented by the official Herdr guide.
Run the client and server on Windows, or use an endpoint-compatible Linux or macOS client to control a Windows workstation or VM. Windows can also connect to compatible Linux and macOS endpoints. A compatible version difference alone does not restart a running server; saved-machine reconnects never install, replace, or start a missing server.
Every supported client can attach to or provision an x86_64 or ARM64 Windows SSH host. Use --yes to approve a required install or restart for one normal attach; unattended provisioning remains explicit:
herdr --remote workbox --yes
herdr --remote workbox --provision --yes --json
The Windows SSH user's OpenSSH default shell must be cmd.exe or PowerShell 7 (pwsh.exe), and persistent server launch requires exactly one active desktop session owned by that user. The first probe is reused for the complete decision, the portable payload transfers once, and visible progress reports every real preparation, validation, stop, activation, verification, and opening phase. Provisioning validates the complete payload before stopping or replacing a server and verifies the exact binary, version, and protocol afterward.
Start OpenCode automatically in the root pane of each genuinely new persistent-session tab:
[session]
auto_start_agent = "opencode"
This managed launch also supplies the ephemeral loopback endpoint used by direct
OpenCode subagent panes. Typing a bare opencode command starts OpenCode's internal
worker transport without that attach endpoint, so use the managed path for this
integration.
Use Settings > completion, or disable completion popups and done sounds without suppressing questions, permission prompts, or errors:
[ui]
notify_on_agent_completion = false
winget upgrade --id hdosys.herdr-win --exact --source wingetherdr updateDirect updates accept only a newer stable CalVer from an immutable normal GitHub release. Active sessions continue on their current immutable runtime and the replacement activates safely afterward; update never terminates running work. herdr update refuses to replace a WinGet-managed installation.
Uninstall from Windows Settings > Apps > Installed apps. Herdr first asks running managed sessions to stop through their graceful server API. If a session remains active, uninstall preserves the installation and reports the required action instead of force-terminating work.
Settings under %USERPROFILE%\.herdr are preserved unless you explicitly choose to remove them. Installer-owned skill files can also be removed explicitly; customized copies and unrelated directory content remain preserved.
| Symptom | Action |
|---|---|
herdr --version does not start with herdr-win | Open a new terminal, run where.exe herdr, and inspect an earlier upstream or user-owned executable on PATH. Setup does not overwrite foreign PATH ownership. |
| Setup rejects an existing Herdr layout | Uninstall the existing Herdr or Herdr Win entry from Installed Apps, then run setup again. The installer preserves and rejects incompatible legacy layouts instead of migrating them. |
| SmartScreen warns about the download | Confirm that the file came from this repository's release page and verify its GitHub SHA-256 digest before choosing to run it. |
| Windows SSH provisioning fails before session start | Confirm that the default OpenSSH shell is cmd.exe or pwsh.exe and that exactly one active desktop session belongs to the SSH user. Windows PowerShell 5.1 is unsupported for this byte-stream path. |
| Update remains pending, or uninstall reports running sessions | Let active work finish or stop the reported Herdr sessions, then launch or retry. The managed lifecycle never force-terminates active work. |
For exact changes in downloadable fork releases, see the herdr-win changelog. For general Herdr behavior, use the upstream documentation and upstream changelog.
This README describes the maintained queue on master. The fork-only changelog is the exact user-facing history for tagged herdr-win releases. Upstream Herdr owns the general CLI, TUI, configuration, integrations, and product documentation.
Patch queue and upstream review
Upstream PR #2329 ships in Herdr v0.8.2. Mailbox 0003 therefore contains only the remaining Windows target-host boundary. Shared client attach, image transport, and SSH bridge behavior come directly from upstream.
The original Windows-host work builds on nsxdavid's feat/windows-remote-attach branch.
The files in patches/delta/series are the complete maintained product delta:
BASE.series in order with git am --3way.CONTRIBUTING.md for replay and verification.The mailboxes are focused evidence, not an all-or-nothing merge request. Fork branding, release workflows, and publication state stay outside the product queue.
Maintaining the project
Refresh and release are separate manual operations:
BASE, run the complete gates, and retain one candidate with provenance and checksums.Ordinary pushes do not publish binaries.
| Need | Canonical owner |
|---|---|
| User-visible fork behavior | PRODUCT.md |
| Technical boundaries | ARCHITECTURE.md |
| Patch ownership and refresh policy | patches/delta/README.md |
| Replay, verification, and release procedure | CONTRIBUTING.md |
| Selected future product work | BACKLOG.md |
CONTRIBUTING.md before changing the queue or release automation.Herdr is created and maintained upstream by Can Çelik. herdr-win is distributed under the Apache License 2.0.