herdr

install · quick start · docs · 简体中文

License: AGPL-3.0-or-later for downstream changes, with retained upstream and third-party rights

An agent multiplexer that lives in your terminal.

• Every agent at a glance — see blocked, working, and done agents in real terminal panes rather than a wrapped interpretation.
• Pane-first workspaces — split, resize, zoom, reorder, and move terminal panes and worktree groups. Keyboard and mouse are both first-class, and pane applications keep their terminal input, scrollback, clipboard, links, palette, and graphics behavior.
• Detach without stopping work — ctrl+b q detaches the client while panes keep running; start Herdr again to reattach. Saved session shape and supported agent conversations can be restored after a server restart.
• Agents can use Herdr too — typed CLI commands, a local socket API, an agent skill, and an opt-in desktop MCP bridge expose pane-oriented automation.
• SSH federation and recovery — compatible Herdr runtimes can delegate a remote pane to one presenting host at a time, explicitly hand it back, and park eligible panes during a graceful stop for later recovery.
• Plugins and integrations — extend pane workflows and report supported agents' lifecycle or resumable session identity.
• Terminal-native UI — no Electron application is required.

This public downstream fork incorporates the original Herdr project exact tag v0.8.0 (peeled commit 346411fa21afd297f5ed3b3fa56f9e3fbf7654b7) and carries the source package version 0.8.0-px.0. Its public fork repository is PeisongXiao/herdr, and compatible runtime peers identify this fork's distribution as peisongxiao/herdr.

This fork supports source-only installation on Linux and macOS x86_64/aarch64:

git clone https://github.com/PeisongXiao/herdr.git
cd herdr
./install-local.sh --check
./install-local.sh

install-local.sh requires Cargo, Rust, a working C compiler/linker, and exactly Zig 0.15.2. It performs a locked build and atomically installs herdr to ~/.local/bin by default. It does not fetch a prebuilt Herdr artifact or use an update channel. To upgrade, pull the source revision you want and rerun the script; then explicitly stop and restart any running Herdr server when you are ready to use the new executable.

Start Herdr where the work lives:

herdr

Run agents, split panes, and walk away. ctrl+b q detaches; herdr reattaches.

Install a protocol-compatible peisongxiao/herdr build from source on every host first. Herdr may find or start an already-installed remote daemon, but it does not provision, copy, replace, or upgrade Herdr on that host.

On Unix, a destination-only interactive ssh workbox launched inside a Herdr pane can register a runtime peer and exclusively present a new remote shell in that pane. For an explicit agent, use:

herdr agent start-remote reviewer --ssh workbox --agent opencode -- opencode

herdr remote-handoff moves a delegated pane into a workspace on its actual host. The opt-in [remote].auto_remote_handoff = true setting parks eligible remote panes during a graceful local server stop so herdr remote-resume can recover them later. These paths are ownership transfers, not simultaneous mirrored panes; failures remain visible and require an explicit retry or recovery action. See persistence and remote access.

On Linux and macOS, supported MCP clients can launch Herdr's local stdio bridge. Automatic configuration is available for supported client IDs, for example:

herdr mcp install codex
herdr mcp status codex

Restricted mode is the default: it can inspect shared panes, while mutation is limited to CLIs launched and registered by that bridge. --full-control is an explicit grant of human-equivalent shared session and runtime control, including destructive tools. This is a same-user capability boundary, not a sandbox against hostile local processes. The bridge does not manage the Herdr server lifecycle. Review the socket API and MCP documentation before enabling it.

• Quick start
• How to work with Herdr
• Agents
• Keyboard
• Configuration
• Session state and restore
• Persistence and remote access
• Integrations
• Plugins
• Socket API and MCP

Read AGENTS.md before making changes and CONTRIBUTING.md before opening an issue or pull request.

git clone https://github.com/PeisongXiao/herdr.git
cd herdr
./install-local.sh --check

just test
just check

Downstream changes in this fork are offered under either of these terms:

1. Open source: GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
2. Commercial: separate terms may be available, but only to the extent the fork owner has the right to grant them.

Material incorporated from upstream Herdr exact tag v0.8.0 (peeled commit 346411fa21afd297f5ed3b3fa56f9e3fbf7654b7) was received under Apache License 2.0. Recipients retain those Apache rights. The provenance statement is in LICENSE, and the exact Apache terms are retained in LICENSE-APACHE. Third-party components remain under their respective notices and licenses.