Herdr

https://herdr.dev/docs
Admin
Herdr is an agent multiplexer that enables running all coding agents from a single terminal across...
Tokens:90,253
Snippets:860
Trust Score:5.2
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install and inspect a GitHub plugin

Source: https://herdr.dev/docs/plugins

Commands to install an example plugin from GitHub shorthand and inspect it. `plugin install` accepts only `owner/repo/subdir` shorthand, clones with git, and registers the plugin.

```bash
herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
herdr plugin config-dir examples.agent-telegram-notify
herdr plugin list
herdr plugin action list --plugin examples.agent-telegram-notify

```

--------------------------------

### Install, list, and remove plugins

Source: https://herdr.dev/docs/cli-reference

Install, list, and remove plugins. Install accepts GitHub shorthand only, uses git, shows a trust preview in interactive terminals, and stores GitHub installs in a Herdr-managed directory. Use --yes for noninteractive installs; reinstalling a GitHub-managed plugin replaces that managed checkout, and installing over a locally linked plugin is refused. Plugin manifests must declare min_herdr_version; install and link fail when the plugin requires a newer Herdr binary. Plugin list is human-readable by default; pass --json for the raw API response.

```bash
herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
herdr plugin list [--plugin ID] [--json]
herdr plugin uninstall <plugin_id|owner/repo[/subdir...]>
herdr plugin enable <plugin_id>
herdr plugin disable <plugin_id>
```

--------------------------------

### Add a machine with default session

Source: https://herdr.dev/docs/connecting-machines

Run setup in an interactive terminal so Herdr can ask before installing or replacing anything. This uses the remote default session.

```bash
herdr machine add workbox --label "Build machine"
```

--------------------------------

### Start an agent with herdr agent start

Source: https://herdr.dev/docs/agent-automation

Starts an agent in a specified pane. The --kind flag selects the agent executable, and arguments after -- are passed to the agent. Returns agent_not_ready if detection reports blocked during startup; waits up to 30 seconds by default.

```bash
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
```

--------------------------------

### Install a plugin from GitHub

Source: https://herdr.dev/docs/marketplace

Installs a plugin from a public GitHub repository. The repository must contain a herdr-plugin.toml manifest at its root or in a subdirectory.

```bash
herdr plugin install owner/repo[/subdir...]
```

--------------------------------

### Install Herdr on Windows via Command Prompt fallback

Source: https://herdr.dev/docs/install

Fallback installation for Windows when endpoint security blocks the fileless PowerShell command. Downloads the installer as install.cmd, runs it, then deletes the file. The installer places the release binary on your PATH and updates the 'current' and stable 'bin' compatibility aliases.

```cmd
curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd
```

--------------------------------

### Install OMP integration with herdr integration install omp

Source: https://herdr.dev/docs/integrations

Installs the OMP integration. Herdr writes the bundled extension to ~/.omp/agent/extensions/herdr-omp-agent-state.ts, or to $PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts if that variable is set. If Pi and OMP resolve to the same extension directory, Herdr refuses the OMP install. The extensions directory is created only when the resolved OMP agent directory already exists; uninstall removes only that extension file.

```shell
herdr integration install omp

```

--------------------------------

### List and invoke plugin actions

Source: https://herdr.dev/docs/cli-reference

List and invoke plugin actions. plugin action invoke starts the manifest command for an installed, enabled, platform-compatible plugin action and prints the started command log record in the JSON response. Use the qualified action id (plugin.id.action) when more than one plugin uses the same action id; local action ids cannot contain dots.

```bash
herdr plugin action list [--plugin ID]
herdr plugin action invoke <action_id> [--plugin ID]
```

--------------------------------

### Run, build, and install Herdr with Nix

Source: https://herdr.dev/docs/install

Use these Nix commands to run, build, or install Herdr from the flake. Replace v0.x.y with the latest release tag, or omit the tag to track master.

```bash
nix run github:herdrdev/herdr/v0.x.y
nix build github:herdrdev/herdr/v0.x.y
nix profile install github:herdrdev/herdr/v0.x.y
```

--------------------------------

### Install OpenCode plugin

Source: https://herdr.dev/docs/integrations

Installs the OpenCode plugin. Supports OpenCode V1 1.18.29 or later and OpenCode V2 (tested with beta 19242). Requires an existing OpenCode config directory. Installs server and TUI plugin files, registers them in tui.jsonc and cli.json, and defers registration if V1 TUI preferences need migration.

```bash
herdr integration install opencode
```

--------------------------------

### Install integration and check status

Source: https://herdr.dev/docs/agents

Install the integration for an agent (e.g., claude) and verify its status. Each supported agent has its own integration name and behavior.

```bash
herdr integration install claude
herdr integration status
```

--------------------------------

### Start Herdr locally

Source: https://herdr.dev/docs/how-to-work

Run `herdr` from the project directory to start or attach to your local background session. You do not manage sockets. Detach with `ctrl+b q`; panes keep running.

```bash
herdr

```

--------------------------------

### Install Pi integration with herdr integration install pi

Source: https://herdr.dev/docs/integrations

Installs the Pi integration. Herdr writes the bundled extension to ~/.pi/agent/extensions/herdr-agent-state.ts, or to $PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts if that variable is set. The extensions directory is created only when the Pi agent directory already exists; uninstall removes only that extension file.

```shell
herdr integration install pi

```

--------------------------------

### Start Herdr from a project directory

Source: https://herdr.dev/docs/quick-start

Runs `herdr` to start or attach to the default background session. Agents keep running when you detach.

```bash
herdr
```

--------------------------------

### Install Qwen Code integration hook

Source: https://herdr.dev/docs/integrations

Run this command to install the Qwen Code hook. The SessionStart hook reports only Qwen Code's session identity for native restore. Herdr uses ~/.qwen by default, or QWEN_HOME when set. The config directory must already exist. Install writes hooks/herdr-agent-session.sh (or .ps1 on Windows) and adds a Herdr entry to settings.json. Uninstall removes only the matching entry and managed script.

```bash
herdr integration install qwen
```

--------------------------------

### Set Herdr channel to preview

Source: https://herdr.dev/docs/install

Opts a direct install into preview builds from the master branch. Preview builds are GitHub prereleases that may regress; Homebrew, mise, and Nix installs do not use this channel.

```bash
herdr channel set preview
```

--------------------------------

### Install Grok CLI hook

Source: https://herdr.dev/docs/integrations

Run this command to install the Herdr integration hook for Grok CLI. Herdr uses ~/.grok by default, or GROK_HOME when set. The config directory must already exist. Install writes a self-contained hooks/herdr.json with the Herdr SessionStart entry and hooks/herdr-agent-state.sh (or .ps1 on Windows), never editing other hook files. Uninstall removes exactly those two Herdr-owned files.

```bash
herdr integration install grok
```

--------------------------------

### Start a helper agent and wait for its work

Source: https://herdr.dev/docs/agent-automation

Starts a helper agent in a new pane, prompts it to review the current diff, and waits for the response. Requires jq to extract the pane ID from the split command's JSON output.

```bash
split=$(herdr pane split --current --direction right --no-focus)
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 120
```

--------------------------------

### Install Hermes Agent plugin

Source: https://herdr.dev/docs/integrations

Installs the Hermes Agent plugin. Herdr writes plugins/herdr-agent-state/ under the Hermes home directory and enables herdr-agent-state in its config.yaml. HERMES_HOME defaults to ~/.hermes on Unix and %LOCALAPPDATA%\hermes on Windows. The Hermes config directory must already exist. Restart Hermes after installing so the plugin loads. Uninstall removes the plugin directory and removes herdr-agent-state from plugins.enabled.

```bash
herdr integration install hermes
```

--------------------------------

### Install Herdr integrations for supported agents

Source: https://herdr.dev/docs/integrations

Run these commands to manually install official integrations for agents found on PATH. Each command targets a specific agent CLI. Use the integrations tab in Herdr settings as an alternative.

```bash
herdr integration install pi
herdr integration install omp
herdr integration install claude
herdr integration install codex
herdr integration install copilot
herdr integration install devin
herdr integration install droid
herdr integration install kimi
herdr integration install opencode
herdr integration install kilo
herdr integration install hermes
herdr integration install qodercli
herdr integration install qwen
herdr integration install letta
herdr integration install cursor
herdr integration install mastracode
herdr integration install antigravity-cli
herdr integration install grok
```

--------------------------------

### Install Claude Code hook with herdr integration install claude

Source: https://herdr.dev/docs/integrations

Installs the Claude Code hook. The hook reports Claude Code session identity to the local Herdr socket on session start. Herdr uses ~/.claude by default, or CLAUDE_CONFIG_DIR when set; the config directory must already exist. Install writes hooks/herdr-agent-state.sh and updates settings.json with Herdr hook entries; uninstall removes the matching hook entries and deletes the hook script.

```shell
herdr integration install claude

```

--------------------------------

### Set onboarding to false

Source: https://herdr.dev/docs/configuration

Disables the first-run setup flow.

```toml
onboarding = false
```

--------------------------------

### Configure shell mode with terminal.shell_mode

Source: https://herdr.dev/docs/configuration

Sets how Herdr starts newly created interactive pane shells. "auto" starts login shells on macOS so login-only PATH setup runs, while other platforms keep non-login behavior. Use "login" or "non_login" to force the mode.

```ini
[terminal]
shell_mode = "auto"
```

--------------------------------

### Connect to remote host with herdr --remote

Source: https://herdr.dev/docs/windows-beta

Use this command from Windows Terminal to connect to a remote host. The target host can run Linux, macOS, or Windows. On Windows hosts, remote attach reuses a compatible package from PATH or the active managed release; interactive direct attach and saved-machine setup prompt before installing or updating the complete package when needed, while background saved reconnect only discovers installed packages and cannot prompt for installation or updates.

```bash
herdr --remote workbox
```

--------------------------------

### Manage saved SSH machines with herdr machine commands

Source: https://herdr.dev/docs/cli-reference

Manage saved SSH machines. By default, `machine add` uses the remote default session; add `--remote-session <name>` only for a named session. `machine list` accepts optional `--json` for scripts. `machine add` checks the remote installation's capabilities, installs or updates with approval only when needed, and starts the requested session's background server before saving. Compatible release versions do not need to match. Run setup in an interactive terminal when installation or restart approval is required; failed or cancelled setup does not save a profile. Replacing a running server requires explicit approval with a default answer of No, and stops its pane processes. `machine add` never enables experimental handoff implicitly. Changes apply automatically to open local Herdr clients, normally within a second. Added or enabled machines connect in the background; renaming does not reconnect. Removing or disabling disconnects only that machine and leaves its remote sessions running. Removing the machine you are viewing returns to Local, or shows Local as unavailable until it reconnects. Each profile stores an opaque ID, label, SSH target, explicit remote session, and enabled state in client state. Herdr does not store passwords, private keys, or other SSH credentials.

```bash
herdr machine list
herdr machine add workbox --label "Build machine"
herdr machine rename <profile-id> --label "New name"
herdr machine disable <profile-id>
herdr machine enable <profile-id>
herdr machine remove <profile-id>
```

--------------------------------

### Install Herdr skill with npx skills

Source: https://herdr.dev/docs/agent-skill

Installs the Herdr skill globally using npx skills. The -g flag installs globally; omit it for project-level installation. Rerun this command if the skill was previously installed at the repository root.

```bash
npx skills add herdrdev/herdr --skill herdr -g
```

--------------------------------

### Print default configuration

Source: https://herdr.dev/docs/config-reference

Use this command to output the full commented default configuration to the terminal.

```bash
herdr --default-config
```

--------------------------------

### Install Herdr with curl

Source: https://herdr.dev/docs

Install Herdr on macOS, Linux, or Windows via the official install script.

```bash
curl -fsSL https://herdr.dev/install.sh | sh
```

--------------------------------

### Set up fpath and compinit for persisted completion

Source: https://herdr.dev/docs/cli-reference

Configures `.zshrc` to include `~/.zfunc` in `fpath` and loads completions via `compinit`.

```shell
fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

```

--------------------------------

### Start agent inside Herdr

Source: https://herdr.dev/docs/agent-skill

Commands to start the agent inside Herdr so HERDR_ENV=1 is available. The first command starts Herdr, the second starts Claude. Any coding agent can be used in a Herdr pane.

```bash
herdr
```

```bash
claude
```

--------------------------------

### Install Herdr with Homebrew

Source: https://herdr.dev/docs/install

Installs Herdr via Homebrew for users who already use Homebrew. This is an alternative to the curl-based installer.

```bash
brew install herdr
```

--------------------------------

### Herdr plugin manifest example (herdr-plugin.toml)

Source: https://herdr.dev/docs/plugins

Complete example of a Herdr plugin manifest. Top-level id, name, version, and min_herdr_version are required. Command values are argv arrays; Herdr does not run them through a shell. Item-level platforms override the top-level list.

```toml
id = "example.layout"
name = "Layout"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "Apply project layouts"
platforms = ["linux", "macos", "windows"]


[[build]]
command = ["npm", "ci"]


[[build]]
command = ["npm", "run", "build"]
platforms = ["linux", "macos"]


[[startup]]
command = ["node", "dist/restore.js"]


[[actions]]
id = "apply"
title = "Apply layout"
contexts = ["workspace"]
command = ["node", "dist/apply.js"]


[[events]]
on = "worktree.created"
command = ["herdr", "workspace", "list"]


[[panes]]
id = "board"
title = "Project board"
placement = "overlay"
command = ["herdr-board"]


[[link_handlers]]
id = "github-issue"
title = "Open GitHub issue"
pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
action = "apply"
```

--------------------------------

### Update Herdr manually

Source: https://herdr.dev/docs/install

Manually updates Herdr. Use only for installs managed by Herdr's own installer; Homebrew, mise, and Nix installs should be updated through their package managers.

```bash
herdr update
```

--------------------------------

### Bind a key to a plugin action with [[keys.command]]

Source: https://herdr.dev/docs/plugins

Binds a key to an installed plugin action. The key is "prefix+l", the type is "plugin_action", and the command names the plugin action to run.

```toml
[[keys.command]]
key = "prefix+l"
type = "plugin_action"
command = "example.layout.apply"
description = "apply layout"
```

--------------------------------

### Install MastraCode integration: herdr integration install mastracode

Source: https://herdr.dev/docs/integrations

Installs the Herdr integration hook for MastraCode. Writes hooks/herdr-agent-state.sh (or .ps1 on Windows) and adds Herdr command entries to hooks.json, creating the directory if missing. Uses ~/.mastracode as the default config directory.

```bash
herdr integration install mastracode
```

--------------------------------

### Open Herdr development shell with Nix

Source: https://herdr.dev/docs/install

Starts a development shell provided by the Herdr flake.

```bash
nix develop github:herdrdev/herdr
```

--------------------------------

### herdr CLI launch and update commands

Source: https://herdr.dev/docs/cli-reference

Launch or attach to the default session, attach through SSH with local keybindings, print default config, update from the configured channel, generate a zsh completion script, show or set the channel (preview or stable), and print the version. Optional flags include --session, --remote-keybindings server, and --handoff for experimental live handoff.

```bash
herdr                         # launch or attach to the default session
herdr --remote workbox        # attach through SSH, using local keybindings
herdr --default-config        # print default config
herdr update                  # download and install from the configured channel
herdr completion zsh          # generate a zsh completion script
herdr channel show            # print stable or preview
herdr channel set preview     # opt into preview builds
herdr channel set stable      # return a direct install to stable
herdr --version               # print version
```

--------------------------------

### Install Herdr on Windows with PowerShell

Source: https://herdr.dev/docs/install

Installs Herdr on Windows using a fileless PowerShell command. If endpoint security blocks this command, use the Command Prompt fallback instead. The installer updates the 'current' and stable 'bin' compatibility aliases so updates do not overwrite a running herdr.exe.

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

--------------------------------

### plugin.action.list

Source: https://herdr.dev/docs/socket-api

Lists all actions across installed plugins.

```APIDOC
## plugin.action.list

### Description
Lists all actions across installed plugins. Optionally filter by plugin ID.

### Method
plugin.action.list

### Parameters
#### Request Body
- **plugin_id** (string) - Optional - Filter actions by plugin ID.

### Request Example
```json
{"id":"req_plugin_actions","method":"plugin.action.list","params":{}}
{"id":"req_plugin_actions_filtered","method":"plugin.action.list","params":{"plugin_id":"example.worktree-bootstrap"}}
```

### Response
#### Success Response
- **actions** (array) - List of actions, each with `id`, `title`, `contexts`, and effective `platforms`.

#### Response Example
```json
{"actions":[{"id":"example.worktree-bootstrap.bootstrap","title":"Bootstrap worktree","contexts":["workspace"],"platforms":["linux","macos","windows"]}]}
```
```

--------------------------------

### Install Cursor Agent CLI integration: herdr integration install cursor

Source: https://herdr.dev/docs/integrations

Installs the Herdr integration hook for Cursor Agent CLI. Writes herdr-agent-state.sh (or .ps1 on Windows) and adds a sessionStart entry to Cursor's hooks.json. Requires the Cursor config directory to exist, defaults to ~/.cursor or CURSOR_CONFIG_DIR.

```bash
herdr integration install cursor
```

--------------------------------

### Manage integrations with herdr integration install/uninstall/status

Source: https://herdr.dev/docs/cli-reference

Lists the `herdr integration` subcommands for installing, uninstalling, and checking the status of integrations. The install and uninstall commands each accept one of the supported integration names (pi, omp, claude, codex, copilot, devin, droid, kimi, opencode, kilo, hermes, qodercli, qwen, letta, cursor, mastracode, grok). The `status` command optionally takes `--outdated-only`.

```bash
herdr integration install pi
herdr integration install omp
herdr integration install claude
herdr integration install codex
herdr integration install copilot
herdr integration install devin
herdr integration install droid
herdr integration install kimi
herdr integration install opencode
herdr integration install kilo
herdr integration install hermes
herdr integration install qodercli
herdr integration install qwen
herdr integration install letta
herdr integration install cursor
herdr integration install mastracode
herdr integration install grok
herdr integration uninstall pi
herdr integration uninstall omp
herdr integration uninstall claude
herdr integration uninstall codex
herdr integration uninstall copilot
herdr integration uninstall devin
herdr integration uninstall droid
herdr integration uninstall kimi
herdr integration uninstall opencode
herdr integration uninstall kilo
herdr integration uninstall hermes
herdr integration uninstall qodercli
herdr integration uninstall qwen
herdr integration uninstall letta
herdr integration uninstall cursor
herdr integration uninstall mastracode
herdr integration uninstall grok
herdr integration status [--outdated-only]

```
Tokens:
Raw