mirror of
https://github.com/herdrdev/herdr.git
synced 2026-09-22 00:01:06 +00:00
docs: publish preview documentation
This commit is contained in:
kangal-bot
@@ -3,7 +3,7 @@ title: Agent automation
|
||||
description: Use Herdr's layout, pane, and agent primitives to coordinate coding agents from scripts or other agents.
|
||||
---
|
||||
|
||||
Herdr can act as an automation layer for coding agents. A script can control them, or one agent can create work for other agents, inspect their state, and collect their results. The important part is choosing the primitive that matches the job.
|
||||
Use Herdr as an automation layer for coding agents. A script can control them, or one agent can create work for other agents, inspect their state, and collect their results. Choose the primitive that matches the job.
|
||||
|
||||
## Three primitives
|
||||
|
||||
@@ -41,9 +41,9 @@ Agent commands accept either a unique live name or the pane ID that currently ho
|
||||
|
||||
An available shell pane is at its interactive shell prompt: the shell itself owns the foreground, with no foreground command, editor, or agent running. Return the pane to its prompt before calling `agent start`.
|
||||
|
||||
`--kind` selects a supported agent and its canonical executable. Supported kinds are `pi`, `claude`, `codex`, `gemini`, `cursor`, `devin`, `agy`, `cline`, `omp`, `mastracode`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `kilo`, `qodercli`, and `maki`. Arguments after `--` are passed unchanged to that executable.
|
||||
`--kind` selects a supported agent and its canonical executable. Supported kinds are `pi`, `claude`, `codex`, `gemini`, `cursor`, `devin`, `agy`, `cline`, `omp`, `mastracode`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `kilo`, `qodercli`, `qwen`, and `maki`. Arguments after `--` are passed unchanged to that executable.
|
||||
|
||||
`agent start` returns only after Herdr detects the expected agent in the same terminal and marks it ready for interactive input. Startup waits for 30 seconds by default; `--timeout` must be greater than 3000 and no more than 300000 milliseconds.
|
||||
Successful `agent start` returns only after Herdr detects the expected agent in the same terminal and marks it ready for interactive input. If detection reports `blocked` during startup, the command returns `agent_not_ready` immediately. The name remains available for `agent read` and `agent send-keys`, and becomes ready for prompts after detection reports `idle`. Startup waits for 30 seconds by default; `--timeout` must be greater than 3000 and no more than 300000 milliseconds.
|
||||
|
||||
```bash
|
||||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
@@ -69,11 +69,11 @@ herdr agent rename w1:p2 reviewer
|
||||
| Send keys to an agent's interactive UI | `agent send-keys` |
|
||||
| Wait for agent lifecycle state | `agent wait` |
|
||||
|
||||
`agent prompt` submits text plus encoded Enter and honors the terminal's live bracketed-paste mode. It can prompt an agent that is already working. Use `agent send-keys` for interactions such as `esc`, `up`, `enter`, or `ctrl+c`; `escape` is accepted as an alias for `esc`. Use the pane input commands when you deliberately want raw terminal control.
|
||||
`agent prompt` submits text plus encoded Enter and honors the terminal's live bracketed-paste mode. It can prompt an agent that is already working. If the agent is already `blocked`, it returns `agent_blocked` without sending terminal input; inspect the dialog and use `agent send-keys` for a deliberate response. Use `agent send-keys` for interactions such as `esc`, `up`, `enter`, or `ctrl+c`; `escape` is accepted as an alias for `esc`. Use the pane input commands when you deliberately want raw terminal control.
|
||||
|
||||
Pane input addresses the terminal regardless of its current occupant. Agent input resolves the live agent and rejects the operation if that agent no longer controls the pane.
|
||||
|
||||
`agent prompt --wait` submits immediately. When the agent starts from a non-working state, Herdr first requires an observed lifecycle change within five seconds. If the state sequence does not advance, it returns `agent_prompt_stalled` instead of waiting indefinitely; a caller `--timeout` of five seconds or less returns the normal `timeout` error. After activity is observed, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`.
|
||||
`agent prompt --wait` submits immediately unless the agent is already `blocked`, in which case it returns `agent_blocked` without starting the wait. If an accepted prompt starts from another non-working state, Herdr must observe a lifecycle change within five seconds. Otherwise, it returns `agent_prompt_stalled` instead of waiting indefinitely; a caller `--timeout` of five seconds or less returns the normal `timeout` error. After Herdr observes activity, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`.
|
||||
|
||||
`idle` means the agent is ready for input and its tab has been seen in the focused Herdr UI. `done` is the same underlying idle state after background work finishes, until that tab is focused or `pane focus` / `agent focus` targets it. Reading through the CLI does not mark it seen. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify its lifecycle confidently; it does not prove successful completion. Use exact `--until` states when that distinction matters.
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ With the skill installed, an agent can:
|
||||
- wait for servers, tests, or another agent to finish
|
||||
- start helper agents in sibling panes
|
||||
|
||||
The skill is not a separate app or service. It is a markdown instruction file for agents. If Herdr is already installed, run `herdr --skill` to print the release-matched copy bundled with that binary.
|
||||
The skill is a Markdown instruction file for agents. If Herdr is already installed, run `herdr --skill` to print the release-matched copy bundled with that binary.
|
||||
|
||||
## Install it
|
||||
|
||||
@@ -50,7 +50,7 @@ herdr
|
||||
claude
|
||||
```
|
||||
|
||||
Or use any other coding agent in a Herdr pane. The important part is that the agent process runs inside Herdr, so `HERDR_ENV=1` is available.
|
||||
Or use any other coding agent in a Herdr pane so `HERDR_ENV=1` is available to the agent process.
|
||||
|
||||
## Safety rule
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ To coordinate agents from scripts or from another agent, see [Agent automation](
|
||||
|
||||
## Supported agents
|
||||
|
||||
Automatic detection works out of the box for common coding agents. The important difference is not whether Herdr can see an agent. It is which signal is allowed to author `idle`, `working`, and `blocked`.
|
||||
Automatic detection works out of the box for common coding agents. The table shows which signal determines `idle`, `working`, and `blocked` for each one.
|
||||
|
||||
| Agent | State authority | Integration role |
|
||||
| --- | --- | --- |
|
||||
@@ -20,6 +20,7 @@ Automatic detection works out of the box for common coding agents. The important
|
||||
| Kimi Code CLI | lifecycle hooks when installed; otherwise screen manifest | state and session |
|
||||
| Hermes Agent | screen manifest | session |
|
||||
| Qoder CLI | screen manifest | session |
|
||||
| Qwen Code | screen manifest | session |
|
||||
| Droid | screen manifest | session |
|
||||
| OpenCode | lifecycle plugin when installed; otherwise screen manifest | state and session |
|
||||
| Kilo Code CLI | lifecycle plugin when installed; otherwise screen manifest | state and session |
|
||||
@@ -49,7 +50,7 @@ Integrations marked `session` in the table above are intentionally not lifecycle
|
||||
|
||||
## VMs and sandbox wrappers
|
||||
|
||||
On Linux and macOS, a host-visible wrapper can hide the real agent process from Herdr. Set `HERDR_AGENT=<agent>` on the wrapper command to tell Herdr which existing agent screen manifest to use. For example, run `HERDR_AGENT=claude fence -- claude` on Linux or `HERDR_AGENT=claude nono run --profile claude-code -- claude` on macOS. The hint is scoped to that foreground process; setting it only inside a VM or container is not visible to Herdr, and you should avoid exporting it globally unless every inherited foreground process should be treated as that agent.
|
||||
On Linux and macOS, a host-visible wrapper can hide the real agent process from Herdr. Set `HERDR_AGENT=<agent>` on the wrapper command to tell Herdr which existing agent screen manifest to use. For example, run `HERDR_AGENT=claude fence -- claude` on Linux or `HERDR_AGENT=claude nono run --profile claude-code -- claude` on macOS. The hint applies only to that foreground process. Herdr cannot see it if you set it only inside a VM or container. Avoid exporting it globally unless every inherited foreground process should be treated as that agent.
|
||||
|
||||
Some restricted Linux runtimes do not expose a terminal foreground process group. Start the Herdr server with `HERDR_PROCESS_DETECTION=child-groups` to opt into direct child-process-group inference when native detection is unavailable. Native detection remains preferred, and the default `native` mode never performs this inference. The opt-in mode is best effort: a newer background job can be mistaken for the foreground job. The variable is read by the server and requires a restart; set it in the remote server environment rather than on an attaching client.
|
||||
|
||||
@@ -57,7 +58,7 @@ Some restricted Linux runtimes do not expose a terminal foreground process group
|
||||
|
||||
Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output.
|
||||
|
||||
This means unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. Those interactions should not make Herdr send input or take destructive action; they only affect the visible status and waits.
|
||||
This means unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. The misclassification affects only the visible status and waits. It should not make Herdr send input or take destructive action.
|
||||
|
||||
## Detection manifests
|
||||
|
||||
@@ -96,14 +97,14 @@ This is the main Herdr workflow: start several agents, let them work in parallel
|
||||
|
||||
## Direct integrations
|
||||
|
||||
Install the integration for each agent you use; it gives Herdr hook or plugin reports instead of screen detection alone:
|
||||
Install the integration for each agent you use to give Herdr hook or plugin reports instead of screen detection alone:
|
||||
|
||||
```bash
|
||||
herdr integration install claude
|
||||
herdr integration status
|
||||
```
|
||||
|
||||
Each supported agent has its own integration name and behavior. See [Integrations](/docs/integrations/) for the per-agent details and the full install list.
|
||||
Each supported agent has its own integration name and behavior. See [Integrations](/docs/integrations/) for the per-agent details and the full install list. If you are building an agent, the [custom integration guide](/docs/integrations/#integrate-your-own-agent) shows how to report lifecycle state without adding native support to Herdr.
|
||||
|
||||
## Custom agent labels
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Herdr commands for sessions, workspaces, tabs, panes, notifications
|
||||
|
||||
Herdr’s CLI talks to the running server over the same local socket API used by integrations and agents.
|
||||
|
||||
Most commands print JSON responses. Use them from scripts when you want deterministic automation.
|
||||
Most commands print JSON responses for deterministic automation in scripts.
|
||||
|
||||
## Launch and status
|
||||
|
||||
@@ -130,7 +130,7 @@ Create a workspace without stealing focus:
|
||||
herdr workspace create --cwd ~/project --label api --no-focus
|
||||
```
|
||||
|
||||
A workspace is the top-level project or work context. Creating one also creates its first tab and root pane. The JSON response exposes their IDs as `.result.workspace.workspace_id`, `.result.tab.tab_id`, and `.result.root_pane.pane_id`.
|
||||
A workspace is a top-level project or work context. Creating one also creates its first tab and root pane. The JSON response exposes their IDs as `.result.workspace.workspace_id`, `.result.tab.tab_id`, and `.result.root_pane.pane_id`.
|
||||
|
||||
## Worktrees
|
||||
|
||||
@@ -143,7 +143,7 @@ herdr worktree remove --workspace ID [--force]
|
||||
|
||||
Worktrees are normal Herdr workspaces with Git checkout provenance. `worktree create` creates a Git worktree checkout, opens it as a workspace, and groups it with the parent repo workspace. If `--branch` names an existing local branch, Herdr checks it out; otherwise it creates the branch from `--base` or `HEAD`. Without `--path`, Herdr creates the checkout under `<worktrees.directory>/<repo>/<branch-slug>`.
|
||||
|
||||
`workspace close` closes Herdr state only. `worktree remove` is the explicit checkout deletion path; it runs `git worktree remove`, never deletes the branch, and requires `--force` when Git refuses a dirty checkout.
|
||||
`workspace close` closes only Herdr state. To delete the checkout, run `worktree remove`. It runs `git worktree remove`, never deletes the branch, and requires `--force` when Git refuses a dirty checkout.
|
||||
|
||||
## Tabs
|
||||
|
||||
@@ -156,7 +156,7 @@ herdr tab rename <tab_id> <label>
|
||||
herdr tab close <tab_id>
|
||||
```
|
||||
|
||||
A tab is another terminal layout inside a workspace. Without `--workspace`, `tab create` uses the active workspace and fails if none exists. Its JSON response exposes `.result.tab.tab_id` and `.result.root_pane.pane_id`. Closing a workspace's last tab also closes the workspace, matching the TUI close-tab action; when `confirm_close` is enabled and that would also close a whole worktree group, `tab close` returns a `confirmation_required` error instead.
|
||||
A tab is another terminal layout inside a workspace. Without `--workspace`, `tab create` uses the active workspace and fails if none exists. Its JSON response exposes `.result.tab.tab_id` and `.result.root_pane.pane_id`. Closing a workspace's last tab also closes the workspace, matching the TUI close-tab action. If `confirm_close` is enabled and closing the tab would also close a whole worktree group, `tab close` returns a `confirmation_required` error instead.
|
||||
|
||||
Workspace and tab creation, and pane splitting, leave focus unchanged by default. `--focus` selects the new layout; `--no-focus` states the default explicitly. Without `--cwd`, new terminals follow the configured `terminal.new_cwd` policy, which follows the source pane or workspace by default. Each `--env KEY=VALUE` adds or replaces that variable in the new root shell.
|
||||
|
||||
@@ -174,7 +174,8 @@ herdr pane focus --direction left|right|up|down [--pane ID|--current]
|
||||
herdr pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current]
|
||||
herdr pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off]
|
||||
herdr pane rename <pane_id> <label>|--clear
|
||||
herdr pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--focus] [--no-focus]
|
||||
herdr pane input [<pane_id>|--pane ID|--current] --right-click herdr|pane
|
||||
herdr pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--right-click herdr|pane] [--focus] [--no-focus]
|
||||
herdr pane swap --direction left|right|up|down [--pane ID|--current]
|
||||
herdr pane swap --source-pane ID --target-pane ID
|
||||
herdr pane move <pane_id> --tab <tab_id> --split right|down [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus]
|
||||
@@ -188,6 +189,12 @@ For pane commands that accept `--current`, Herdr uses the calling pane's
|
||||
an explicit pane id or `--pane ID` splits that pane, `--current` splits the
|
||||
calling pane, and an omitted target keeps using the UI-focused pane.
|
||||
The split response exposes the new pane ID as `.result.pane.pane_id`.
|
||||
|
||||
`pane input --right-click pane` forwards unmodified right-click gestures to a
|
||||
mouse-reporting pane application. `herdr` restores the default pane menu.
|
||||
Right-clicking the pane frame still opens Herdr's menu. `pane split
|
||||
--right-click pane` applies the same policy to the new pane at creation.
|
||||
|
||||
After `pane move`, use `.result.move_result.pane.pane_id` for later commands. A cross-workspace move changes the workspace-qualified pane ID; the prior value remains at `.result.move_result.previous_pane_id`. The running process keeps its launch-time `HERDR_PANE_ID`, `HERDR_TAB_ID`, and `HERDR_WORKSPACE_ID`; Herdr retains the old pane ID as an alias for that terminal, so pane commands using `--current` still resolve it. A live agent name follows the terminal and continues to resolve after the move.
|
||||
|
||||
Read output:
|
||||
@@ -248,7 +255,7 @@ herdr pane release-agent <pane_id> \
|
||||
|
||||
`pane get`, `pane list`, `agent get`, and `agent list` include a read-only `agent_session` object when an official integration has reported a native session reference. If no native session reference is stored, the field is omitted.
|
||||
|
||||
Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The existing `cwd` field remains the pane/workspace cwd used for labels and follow-cwd behavior.
|
||||
Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The `cwd` field remains the pane/workspace cwd used for labels and follow-cwd behavior.
|
||||
|
||||
`pane get` and `pane list` include `scroll` when terminal scroll metrics are available. `scroll.offset_from_bottom == 0` means the pane is at the bottom of its scrollback.
|
||||
|
||||
@@ -298,11 +305,11 @@ herdr agent explain --file PATH --agent LABEL [--json|--verbose]
|
||||
|
||||
Agent targets are either a unique live agent name or the pane ID that currently hosts the agent. Terminal IDs and bare agent-kind labels are not agent targets. Agents started through `agent start` require a name; manually launched agents remain unnamed and use their pane ID.
|
||||
|
||||
`agent start` activates an existing available shell pane: the pane's interactive shell must own the foreground, with no foreground command, editor, or agent running. Topology must be created separately. Names are unique among live agents and must match `[a-z][a-z0-9_-]{0,31}`. The kind selects Herdr's canonical interactive executable, while arguments after `--` are passed to that executable. Supported kinds are `pi`, `claude`, `codex`, `gemini`, `cursor`, `devin`, `agy`, `cline`, `omp`, `mastracode`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `kilo`, `qodercli`, and `maki`. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced. Temporary detection uncertainty does not clear it.
|
||||
`agent start` activates an existing available shell pane: the pane's interactive shell must own the foreground, with no foreground command, editor, or agent running. Topology must be created separately. Names are unique among live agents and must match `[a-z][a-z0-9_-]{0,31}`. The kind selects Herdr's canonical interactive executable, while arguments after `--` are passed to that executable. Supported kinds are `pi`, `claude`, `codex`, `gemini`, `cursor`, `devin`, `agy`, `cline`, `omp`, `mastracode`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `kilo`, `qodercli`, `qwen`, and `maki`. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced. Temporary detection uncertainty does not clear it.
|
||||
|
||||
Start returns only after the expected agent owns the same terminal and is ready for interactive input. The default startup timeout is 30000 milliseconds; explicit values must be greater than 3000 and no more than 300000.
|
||||
A successful start returns only after the expected agent owns the same terminal and is ready for interactive input. If detection reports `blocked` during startup, the command returns `agent_not_ready` immediately. The name remains available for `agent read` and `agent send-keys`, and becomes ready for prompts after detection reports `idle`. The default startup timeout is 30000 milliseconds; explicit values must be greater than 3000 and no more than 300000.
|
||||
|
||||
`agent prompt` honors live bracketed-paste mode and submits text plus encoded Enter atomically, including while the agent is working. With `--wait`, a prompt sent from a non-working state must produce an observed lifecycle change within five seconds or Herdr returns `agent_prompt_stalled`; a caller timeout of five seconds or less keeps the normal `timeout` error. After activity is observed, it waits for the first requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. `--until` narrows the matching states and is rejected unless `--wait` is also present. Standalone `agent wait` returns immediately when the current status matches. Both default to `idle`, `done`, or `blocked`; use `--until unknown` explicitly when needed.
|
||||
`agent prompt` honors live bracketed-paste mode and sends text followed by encoded Enter after a short delay, including while the agent is working. If the agent is already `blocked`, it returns `agent_blocked` without sending input. With `--wait`, an accepted prompt sent from another non-working state must produce an observed lifecycle change within five seconds or Herdr returns `agent_prompt_stalled`; a caller timeout of five seconds or less keeps the normal `timeout` error. After activity is observed, it waits for the first requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. `--until` narrows the matching states and is rejected unless `--wait` is also present. Standalone `agent wait` returns immediately when the current status matches. Both default to `idle`, `done`, or `blocked`; use `--until unknown` explicitly when needed.
|
||||
|
||||
`idle` means ready for input after its tab has been seen in the focused Herdr UI; `done` is the same underlying idle state after unseen background work completes. Focusing that tab or targeting it with `pane focus` / `agent focus` marks it seen; reading it through the CLI does not. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently, not that its work succeeded.
|
||||
|
||||
@@ -334,7 +341,7 @@ terminal, or agent target. It prints newline-delimited JSON `terminal.frame`
|
||||
records with base64-encoded ANSI bytes, then a `terminal.closed` record when
|
||||
the server closes the stream. Multiple observers can watch the same terminal
|
||||
without taking input, resize, scroll, or takeover authority.
|
||||
`terminal title clear` restores Herdr's default outer terminal window title.
|
||||
`terminal title clear` hands the outer terminal window title back to `ui.window_title`.
|
||||
|
||||
## Output waits
|
||||
|
||||
@@ -365,6 +372,7 @@ herdr integration install opencode
|
||||
herdr integration install kilo
|
||||
herdr integration install hermes
|
||||
herdr integration install qodercli
|
||||
herdr integration install qwen
|
||||
herdr integration install cursor
|
||||
herdr integration install mastracode
|
||||
herdr integration install grok
|
||||
@@ -380,6 +388,7 @@ herdr integration uninstall opencode
|
||||
herdr integration uninstall kilo
|
||||
herdr integration uninstall hermes
|
||||
herdr integration uninstall qodercli
|
||||
herdr integration uninstall qwen
|
||||
herdr integration uninstall cursor
|
||||
herdr integration uninstall mastracode
|
||||
herdr integration uninstall grok
|
||||
@@ -411,7 +420,7 @@ herdr plugin link <path> [--disabled]
|
||||
herdr plugin unlink <plugin_id>
|
||||
```
|
||||
|
||||
`plugin link` accepts a plugin directory containing `herdr-plugin.toml` or a direct manifest path. It is still the right command while authoring or testing a plugin from a local checkout. `plugin unlink` unregisters the plugin and leaves files alone. `plugin uninstall` unregisters a plugin and also removes Herdr-managed GitHub checkout files. For GitHub installs, uninstall accepts either the plugin id or the same `owner/repo[/subdir...]` shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.
|
||||
`plugin link` accepts a plugin directory containing `herdr-plugin.toml` or a direct manifest path. Use it while authoring or testing a plugin from a local checkout. `plugin unlink` unregisters the plugin and leaves files alone. `plugin uninstall` unregisters a plugin and also removes Herdr-managed GitHub checkout files. For GitHub installs, uninstall accepts either the plugin id or the same `owner/repo[/subdir...]` shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.
|
||||
|
||||
Config directory:
|
||||
|
||||
@@ -419,7 +428,7 @@ Config directory:
|
||||
herdr plugin config-dir <plugin_id>
|
||||
```
|
||||
|
||||
`plugin config-dir` prints the plugin's config directory, creating it (and seeding it from legacy plugin config locations when present) if needed. Use it in setup docs and shell scripts to point users at a stable path for `.env` files and other user-editable config, separate from the managed plugin checkout.
|
||||
`plugin config-dir` prints the plugin's config directory. It creates the directory if needed and seeds it from legacy plugin config locations when present. Use it in setup docs and shell scripts to point users at a stable path for `.env` files and other user-editable config, separate from the managed plugin checkout.
|
||||
|
||||
Actions:
|
||||
|
||||
@@ -457,7 +466,7 @@ layout. `--width` and `--height` set the outer popup dimensions in terminal
|
||||
cells or percentages such as `80%`; omitted dimensions default to half the
|
||||
terminal size, and values smaller than the popup minimum are clamped. A popup
|
||||
is not a Herdr pane, does not export `HERDR_PANE_ID`, and does not participate
|
||||
in pane or agent APIs. Native non-terminal plugin panes are a later surface.
|
||||
in pane or agent APIs. Native non-terminal plugin panes are outside plugin v1.
|
||||
|
||||
`--env KEY=VALUE` can be repeated on process-launching commands. It applies to the newly launched process only. Herdr-managed variables such as `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ENV`, `HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, `HERDR_PANE_ID`, `HERDR_PLUGIN_ID`, `HERDR_PLUGIN_ROOT`, `HERDR_PLUGIN_CONFIG_DIR`, `HERDR_PLUGIN_STATE_DIR`, `HERDR_PLUGIN_ENTRYPOINT_ID`, and `HERDR_PLUGIN_CONTEXT_JSON` stay authoritative when they conflict with caller-provided env.
|
||||
|
||||
|
||||
@@ -82,4 +82,4 @@ Herdr has terminal mode, prefix mode, and navigate mode.
|
||||
|
||||
Terminal mode sends keys to the focused pane. Prefix mode waits for one Herdr action after the prefix key. Navigate mode is the persistent workspace navigation surface.
|
||||
|
||||
Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation. New to the prefix idea? See [Keyboard](/docs/keyboard/).
|
||||
Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation. See [Keyboard](/docs/keyboard/) if the prefix idea is new to you.
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Every canonical config.toml key, with types, defaults, and allowed
|
||||
|
||||
import ConfigReference from '../../components/ConfigReference.astro';
|
||||
|
||||
Every canonical key Herdr reads from `config.toml`, flat and filterable. For guided setup
|
||||
Browse every canonical key Herdr reads from `config.toml` in a flat, filterable list. For setup guidance
|
||||
and the reasoning behind these options, see [Configuration](/docs/configuration/).
|
||||
|
||||
Print the full commented default config at any time:
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Configure Herdr keybindings, themes, sidebar behavior, notification
|
||||
|
||||
Herdr works without a config file. Add one when you want custom keys, themes, sidebar layouts, notifications, or advanced behavior.
|
||||
|
||||
Looking for any setting or keybinding? Search the [Config reference](/docs/config-reference/) for every key, type, default, and allowed value. This page focuses on setup, common recipes, and configuration structures that need more explanation than a reference row.
|
||||
The [Config reference](/docs/config-reference/) lists every setting and keybinding, with types, defaults, and allowed values. This page covers setup, common recipes, and configuration structures that need more explanation than a reference row.
|
||||
|
||||
## Config file
|
||||
|
||||
@@ -32,7 +32,7 @@ herdr --default-config > ~/.config/herdr/config.toml
|
||||
|
||||
If a config value is invalid, Herdr falls back to a safe default and shows a startup warning.
|
||||
|
||||
Herdr shows first-run setup when `onboarding` is missing or true. Continuing from onboarding writes `onboarding = false` and opens settings on the integrations tab. Set it when you want to skip that flow after setup.
|
||||
Herdr shows first-run setup when `onboarding` is missing or true. Continuing from onboarding writes `onboarding = false` and opens settings on the integrations tab. Set `onboarding = false` to skip that flow after setup.
|
||||
|
||||
```toml
|
||||
onboarding = false
|
||||
@@ -50,6 +50,18 @@ You can also open the global menu in Herdr and choose `reload config`.
|
||||
|
||||
Reload applies most UI settings without restarting panes. Startup-only settings still need a restart.
|
||||
|
||||
## Headless terminal size
|
||||
|
||||
When no client is attached, the server uses a 120×40 virtual terminal for layout and newly created panes. Change that fallback for headless orchestration with:
|
||||
|
||||
```toml
|
||||
[server]
|
||||
headless_cols = 160
|
||||
headless_rows = 50
|
||||
```
|
||||
|
||||
An attached client remains authoritative for the shared runtime size. After it detaches, existing pane PTYs retain their last attached size while new headless layout uses the configured fallback.
|
||||
|
||||
## Terminal defaults
|
||||
|
||||
Set the executable Herdr uses for newly created interactive panes:
|
||||
@@ -68,7 +80,7 @@ Set how Herdr starts newly created interactive pane shells:
|
||||
shell_mode = "auto"
|
||||
```
|
||||
|
||||
`shell_mode = "auto"` starts login shells on macOS so login-only PATH setup such as `/usr/libexec/path_helper` and Homebrew shell initialization runs in new panes. On other platforms, it keeps the existing non-login shell behavior. Use `"login"` to force login-shell startup, or `"non_login"` to opt out. Command panes, detached custom command keybindings, and explicit argv launches keep their existing command execution paths.
|
||||
`shell_mode = "auto"` starts login shells on macOS so login-only PATH setup such as `/usr/libexec/path_helper` and Homebrew shell initialization runs in new panes. On other platforms, it keeps the existing non-login shell behavior. Use `"login"` to force login-shell startup or `"non_login"` to force non-login startup. Command panes, detached custom command keybindings, and explicit argv launches keep their existing command execution paths.
|
||||
|
||||
Set the working directory policy for new panes, tabs, and workspaces:
|
||||
|
||||
@@ -90,22 +102,22 @@ directory = "~/.herdr/worktrees"
|
||||
|
||||
Herdr creates checkouts under `<directory>/<repo>/<branch-slug>`. For sibling-style checkouts, set this to a directory such as `~/Projects/herdr-worktrees`. Relative values are resolved to an absolute path when the app applies the config.
|
||||
|
||||
Worktree actions are available from Git workspace rows. `New worktree` creates a checkout, checks out an existing local branch when the entered branch already exists, otherwise creates the branch, opens it as a new Herdr workspace, and groups it under the source workspace. `Open worktree...` lists existing Git worktree checkouts for that repo; choosing an already-open checkout focuses it, and choosing a closed checkout opens it in the same group.
|
||||
Worktree actions are available from Git workspace rows. `New worktree` creates a checkout. It checks out an existing local branch when the entered branch exists; otherwise, it creates the branch. It then opens the checkout as a new Herdr workspace and groups it under the source workspace. `Open worktree...` lists existing Git worktree checkouts for that repo. Choosing an already-open checkout focuses it, while choosing a closed checkout opens it in the same group.
|
||||
|
||||
Grouped worktrees still behave like normal Herdr workspaces: they can be focused, renamed, closed, and contain their own tabs and panes. The parent row is the original workspace. Closing the parent row closes the whole Herdr group, but it does not delete checkout folders or branches.
|
||||
|
||||
Deleting a worktree checkout is explicit. Use `Delete worktree checkout...` on a grouped child workspace to run `git worktree remove`. Herdr first asks Git to remove safely. If Git refuses because the checkout has modified or untracked files, Herdr asks again before running the forced remove. Branches are not deleted.
|
||||
To delete a worktree checkout, use `Delete worktree checkout...` on a grouped child workspace. Herdr runs `git worktree remove`, first asking Git to remove safely. If Git refuses because the checkout has modified or untracked files, Herdr asks again before running the forced remove. Branches are not deleted.
|
||||
|
||||
## Remote attach
|
||||
|
||||
Remote attach manages its SSH connection with a temporary keepalive and connection-reuse fallback by default.
|
||||
Remote attach manages its SSH connection with temporary keepalives and, where supported, connection reuse by default.
|
||||
|
||||
```toml
|
||||
[remote]
|
||||
manage_ssh_config = true
|
||||
```
|
||||
|
||||
When enabled, `herdr --remote` writes a private temporary SSH config that includes your `~/.ssh/config` and `/etc/ssh/ssh_config` first, then adds fallback `ServerAliveInterval` and `ServerAliveCountMax` values. Your own keepalive settings win. Herdr also uses a private per-attach OpenSSH control socket to reuse the first authenticated connection. Set `manage_ssh_config = false` to run remote attach through plain `ssh` without Herdr's generated config or control socket.
|
||||
When enabled, `herdr --remote` writes a private temporary SSH config that includes your user and system SSH configs first, then adds fallback `ServerAliveInterval` and `ServerAliveCountMax` values. Your own keepalive settings win. Linux and macOS clients also use a private per-attach OpenSSH control socket to reuse the first authenticated connection; Windows OpenSSH does not. Set `manage_ssh_config = false` to run remote attach through plain `ssh` without Herdr's generated config or control socket.
|
||||
|
||||
## Keybindings
|
||||
|
||||
@@ -137,7 +149,15 @@ A binding may also be an array when one action needs multiple shortcuts:
|
||||
next_tab = ["prefix+n", "ctrl+alt+]"]
|
||||
```
|
||||
|
||||
Optional actions are unset by default. Bind them with `prefix+` for prefix-mode behavior, or use an explicit modified chord when you intentionally want a direct shortcut.
|
||||
Optional actions are unset by default. Bind them with `prefix+` for prefix-mode behavior, or use an explicit modified chord when you intentionally want a direct shortcut. For example, tmux-style one-keystroke pane resizing without entering resize mode:
|
||||
|
||||
```toml
|
||||
[keys]
|
||||
resize_pane_left = "ctrl+shift+alt+left"
|
||||
resize_pane_down = "ctrl+shift+alt+down"
|
||||
resize_pane_up = "ctrl+shift+alt+up"
|
||||
resize_pane_right = "ctrl+shift+alt+right"
|
||||
```
|
||||
|
||||
Key strings accept plain keys, modifier combinations such as `ctrl+a`, `shift+n`, `alt+1`, `cmd+k`, and special keys such as `enter`, `tab`, `esc`, `left`, `right`, `up`, and `down`. Named punctuation such as `minus`, `comma`, `ampersand`, `plus`, and `backtick` is also accepted. Plain direct printable keys such as `n` are unsafe because they intercept typing; use `prefix+n` unless you intentionally want a direct binding. The `navigate_workspace_*` and `navigate_pane_*` fields are navigate-mode-only and may use plain keys such as `j` or `k`; they must not use `prefix+`, `esc`, `enter`, `tab`, `shift+tab`, `left`, `right`, or unmodified `1` through `9`. Left and right arrows are permanent aliases for pane-left and pane-right navigation. These navigate-mode shortcuts are independent from general action bindings such as `focus_pane_down = "prefix+j"`; when both use the same key, the navigate-mode shortcut wins while navigate mode is open. Alt, Cmd/Super, and punctuation with modifiers depend on your terminal and tmux settings.
|
||||
|
||||
@@ -209,7 +229,7 @@ command = "example.layout.apply"
|
||||
description = "apply layout"
|
||||
```
|
||||
|
||||
An optional `description` can be provided. When specified, this description is displayed in the keybind help panel (opened with `prefix+?`) in place of the default `'custom command'` label.
|
||||
`description` is optional. When set, it appears in the keybind help panel (opened with `prefix+?`) instead of the default `'custom command'` label.
|
||||
|
||||
Custom commands receive `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ACTIVE_WORKSPACE_ID`, `HERDR_ACTIVE_TAB_ID`, `HERDR_ACTIVE_PANE_ID`, and `HERDR_ACTIVE_PANE_CWD` when those values are available. Shell commands run from the focused pane's working directory when Herdr can detect it.
|
||||
|
||||
@@ -242,6 +262,9 @@ You can override individual colors:
|
||||
|
||||
```toml
|
||||
[theme.custom]
|
||||
sidebar_bg = "#181825"
|
||||
active_row_bg = "#1e1e2e"
|
||||
selection_bg = "#313244"
|
||||
panel_bg = "reset"
|
||||
accent = "#a6e3a1"
|
||||
green = "#a6e3a1"
|
||||
@@ -250,6 +273,8 @@ red = "#f38ba8"
|
||||
yellow = "#f9e2af"
|
||||
```
|
||||
|
||||
`sidebar_bg` optionally gives the desktop sidebar its own background. When omitted, the sidebar keeps the host terminal background. `active_row_bg` changes the active Space and focused Agent row background without affecting separators or scrollbar tracks. `selection_bg` changes the Navigate-mode cursor row background in the sidebar.
|
||||
|
||||
Color values accept hex, named colors, `rgb(r,g,b)`, or reset aliases like `reset`, `default`, `none`, and `transparent`.
|
||||
|
||||
## UI and sidebar
|
||||
@@ -258,6 +283,50 @@ The sidebar is the main Herdr dashboard. Search `ui.` in the [Config reference](
|
||||
|
||||
Set `tab_bar_position = "bottom"` under `[ui]` to place the desktop tab row below the terminal panes. Prefix, Navigate, Copy, and Resize mode bars temporarily replace the bottom tab row while active. The default is `"top"`.
|
||||
|
||||
Configure an ordered tmux-style status area at the right edge of the tab row:
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
tab_bar_right = [
|
||||
{ type = "zoom" },
|
||||
{ type = "hostname" },
|
||||
{ type = "datetime", format = "%H:%M" },
|
||||
{ type = "text", text = "prod" },
|
||||
{ type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
|
||||
]
|
||||
tab_bar_right_separator = " · "
|
||||
```
|
||||
|
||||
The status area is empty by default. Add `zoom` to show a fixed `ZOOM` pill while the active tab is zoomed; the existing per-tab `Z` markers remain independent. `hostname`, `datetime`, and `command` resolve on the Herdr server, so `herdr --remote` shows the remote machine's values. Datetime entries use `strftime` formatting; directives that require a UTC offset or Unix timestamp, such as `%z` and `%s`, are rejected because the value is server-local wall-clock time.
|
||||
|
||||
Command entries run immediately and then at `interval_seconds` without blocking rendering or overlapping a previous run. The interval can be 1–31,536,000 seconds and the timeout can be 1–3,600 seconds. Herdr uses the last line of successful output, clears it after failure, empty output, or `timeout_seconds`, and provides the same active workspace, tab, pane, socket, binary, and working-directory context as custom command keybindings. Commands are supported on Linux, macOS, and Windows, using `/bin/sh -lc` on Linux and macOS and `cmd.exe /d /c` on Windows.
|
||||
|
||||
Separators appear only between visible entries. Set `tab_bar_right_separator = ""` for direct concatenation. On a narrow tab row, the complete status area yields to the tabs and their controls.
|
||||
|
||||
### Outer terminal window title
|
||||
|
||||
Herdr emulates the terminals in its panes, so an `OSC 0`/`OSC 2` title written inside a pane stops at Herdr. Herdr writes its own title to the terminal it runs in, which is what window managers and terminal tab bars read:
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
window_title = "{hostname}: {workspace}"
|
||||
```
|
||||
|
||||
Tokens are `{hostname}`, `{workspace}`, `{tab}`, `{pane}` (the focused pane's manual name), and `{terminal_title}` (the focused pane's own terminal title with spinner frames stripped). Write `{{` and `}}` for literal braces. A token with no value renders empty.
|
||||
|
||||
The title renders on the Herdr server, so `{hostname}` names the machine the panes run on, including when you attach with `herdr --remote` or run `herdr` over SSH. Set `window_title = ""` to leave the outer terminal title alone.
|
||||
|
||||
`client.window_title.set` overrides the configured title until `client.window_title.clear` hands it back.
|
||||
|
||||
Agent status uses compact colored dots by default. To distinguish blocked, working, done, idle, and unknown states by shape as well as color, choose **distinct symbols** in Settings or configure:
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
status_indicators = "symbols"
|
||||
```
|
||||
|
||||
The symbols are static, so this option does not enable spinner animation.
|
||||
|
||||
### Sidebar row layouts
|
||||
|
||||
The expanded desktop sidebar renders each inner array in `rows` as one line. These are the complete default layouts:
|
||||
@@ -352,7 +421,7 @@ herdr pane report-metadata <pane_id> \
|
||||
--token summary="reviewing authentication"
|
||||
```
|
||||
|
||||
Use `herdr workspace report-metadata` in the same way for custom Space tokens. Unreported custom tokens simply disappear.
|
||||
Use `herdr workspace report-metadata` in the same way for custom Space tokens. Unreported custom tokens disappear.
|
||||
|
||||
Metadata reporters provide values only; styling stays in the local sidebar configuration. See [CLI reference: report metadata](/docs/cli-reference/#panes) for limits, clearing, sequencing, and expiry.
|
||||
|
||||
@@ -371,11 +440,13 @@ delay_seconds = 1
|
||||
position = "bottom-right"
|
||||
```
|
||||
|
||||
Choose `herdr` for an in-app toast, `terminal` for an outer-terminal notification that works well over SSH, `system` for the local OS notification service, or `off` to disable popups. Herdr suppresses popups for the active tab. Search `ui.toast` in the [Config reference](/docs/config-reference/) for positions, delay behavior, and clipboard feedback settings.
|
||||
Choose `herdr` for an in-app toast, `terminal` for an outer-terminal notification that also works over SSH, `system` for the local OS notification service, or `off` to disable popups. Herdr suppresses popups for the active tab. Search `ui.toast` in the [Config reference](/docs/config-reference/) for positions, delay behavior, and clipboard feedback settings.
|
||||
|
||||
On macOS, `system` tries `terminal-notifier` first and falls back to `/usr/bin/osascript` when it is unavailable or fails. The fallback appears as Script Editor in Notification Center and cannot activate the hosting terminal. Install `terminal-notifier` with `brew install terminal-notifier`. For a supported, detected terminal, it can activate the terminal app when you click the notification. Alternatively, choose `terminal` to let a supported outer terminal own the notification.
|
||||
|
||||
## Sound
|
||||
|
||||
Sound notifications play through the local Herdr client. Custom sounds must be mp3 files; relative paths are resolved from the config file's directory.
|
||||
Sound notifications play through the local Herdr client. Custom sounds must be mp3 files; Herdr resolves relative paths from the config file's directory.
|
||||
|
||||
```toml
|
||||
[ui.sound]
|
||||
|
||||
@@ -42,11 +42,11 @@ herdr
|
||||
|
||||
This works like a terminal multiplexer. Your shell is remote. The Herdr server is remote. The agents and panes run on the remote machine. Detach with `ctrl+b q`, disconnect, then SSH back and run `herdr` again.
|
||||
|
||||
Use this path when you already live inside an SSH shell, when you are on a phone or tablet SSH client, or when you want the simplest possible setup.
|
||||
Use this path when you already live inside an SSH shell, when you are on a phone or tablet SSH client, or when you want the simplest setup.
|
||||
|
||||
## Work from your phone
|
||||
|
||||
You do not need a Herdr mobile app or a web dashboard. Install any SSH client on your phone, connect to the machine where your agents run, and start Herdr there:
|
||||
Herdr works on your phone without a mobile app or web dashboard. Install any SSH client, connect to the machine where your agents run, and start Herdr there:
|
||||
|
||||
```bash
|
||||
ssh you@server
|
||||
|
||||
@@ -33,13 +33,13 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
|
||||
|
||||
## Or let your agent introduce you
|
||||
|
||||
Already running an AI coding agent? Let it do the onboarding. Paste this prompt:
|
||||
If you already run an AI coding agent, let it handle the onboarding. Paste this prompt:
|
||||
|
||||
```text
|
||||
Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step.
|
||||
```
|
||||
|
||||
The guide teaches your agent Herdr's concepts, setup, configuration, and common fixes, so its answers stay accurate instead of improvised.
|
||||
The guide covers Herdr's concepts, setup, configuration, and common fixes, so your agent can answer from the docs instead of improvising.
|
||||
|
||||
## Core guides
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ On Windows preview beta, install the preview channel:
|
||||
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
|
||||
```
|
||||
|
||||
The installer downloads the right release binary for your platform and places it on your PATH. Herdr defaults to preview on Windows without changing your config. The installer uses versioned install folders and updates a `current` junction, so updates do not need to overwrite a running `herdr.exe`.
|
||||
The installer downloads the release binary for your platform and installs it in a directory on your PATH. Herdr defaults to preview on Windows without changing your config. The installer uses versioned install folders and updates a `current` junction, so updates do not need to overwrite a running `herdr.exe`.
|
||||
|
||||
## Install with Homebrew
|
||||
|
||||
@@ -57,7 +57,7 @@ The flake also exposes a development shell:
|
||||
nix develop github:herdrdev/herdr
|
||||
```
|
||||
|
||||
Update through the same Nix workflow you used to install Herdr. For a profile install, list your profile entries and upgrade the Herdr entry:
|
||||
Use the same Nix workflow to update Herdr. For a profile install, list your profile entries and upgrade the Herdr entry:
|
||||
|
||||
```bash
|
||||
nix profile list
|
||||
@@ -118,7 +118,7 @@ Herdr checks for new releases and notifies you in the app. You can update manual
|
||||
herdr update
|
||||
```
|
||||
|
||||
`herdr update` is for installs managed by Herdr's own installer. Homebrew, mise, and Nix installs are updated through those package managers instead.
|
||||
Use `herdr update` only for installs managed by Herdr's own installer. Update Homebrew, mise, and Nix installs through those package managers instead.
|
||||
|
||||
On Linux and macOS, Herdr uses the stable update channel by default. To opt into preview builds from `master`, set the channel:
|
||||
|
||||
@@ -132,13 +132,13 @@ Switch Linux and macOS direct installs back to stable the same way:
|
||||
herdr channel set stable
|
||||
```
|
||||
|
||||
For direct installs, changing channels also checks that channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
|
||||
For direct installs, changing channels checks the selected channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
|
||||
|
||||
Preview builds are manually published GitHub prereleases from the current development branch. They are useful when you want fixes before the next stable release, but they can regress. Homebrew, mise, and Nix installs do not use the preview channel.
|
||||
|
||||
Windows beta builds are preview-only for now. `herdr channel set stable` is rejected on Windows until stable Windows releases are available.
|
||||
|
||||
By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping exits pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
|
||||
By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping the server exits its pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
|
||||
|
||||
To opt into experimental live server handoff for supported running sessions, run:
|
||||
|
||||
|
||||
@@ -1,11 +1,9 @@
|
||||
---
|
||||
title: Integrations
|
||||
description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, Qoder CLI, Cursor Agent CLI, MastraCode, Antigravity CLI, and Grok CLI.
|
||||
description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, Qoder CLI, Qwen Code, Cursor Agent CLI, MastraCode, Antigravity CLI, and Grok CLI.
|
||||
---
|
||||
|
||||
Herdr detects supported agents automatically. Official integrations can add native session identity for restore, lifecycle state reports, or both.
|
||||
|
||||
Use integrations when you want native agent session restore, direct lifecycle reports, or both. See [Agents](/docs/agents/) for the full status authority model.
|
||||
Herdr detects supported agents automatically. Install official integrations when you want native agent session restore, direct lifecycle reports, or both. See [Agents](/docs/agents/) for the full status authority model.
|
||||
|
||||
## Install integrations
|
||||
|
||||
@@ -24,6 +22,7 @@ herdr integration install opencode
|
||||
herdr integration install kilo
|
||||
herdr integration install hermes
|
||||
herdr integration install qodercli
|
||||
herdr integration install qwen
|
||||
herdr integration install cursor
|
||||
herdr integration install mastracode
|
||||
herdr integration install antigravity-cli
|
||||
@@ -45,6 +44,7 @@ herdr integration uninstall opencode
|
||||
herdr integration uninstall kilo
|
||||
herdr integration uninstall hermes
|
||||
herdr integration uninstall qodercli
|
||||
herdr integration uninstall qwen
|
||||
herdr integration uninstall cursor
|
||||
herdr integration uninstall mastracode
|
||||
herdr integration uninstall antigravity-cli
|
||||
@@ -53,18 +53,45 @@ herdr integration uninstall grok
|
||||
|
||||
## How Herdr uses integrations
|
||||
|
||||
Herdr uses integrations in two different ways:
|
||||
Herdr uses integrations in two ways:
|
||||
|
||||
| Integration type | Agents | Effect |
|
||||
| --- | --- | --- |
|
||||
| Lifecycle authority | Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, MastraCode | When installed and actively reporting for the pane, hook or plugin events author `idle`, `working`, and `blocked`. Herdr does not also use screen manifest fallback for that same lifecycle authority. |
|
||||
| Session identity | Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Qoder CLI, Cursor Agent CLI, Hermes Agent, Antigravity CLI, Grok CLI | The integration reports native session references for restore. State still comes from Herdr's screen manifest detection. |
|
||||
| Session identity | Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Qoder CLI, Qwen Code, Cursor Agent CLI, Hermes Agent, Antigravity CLI, Grok CLI | The integration reports native session references for restore. State still comes from Herdr's screen manifest detection. |
|
||||
|
||||
Custom socket integrations can also report state when they define state that is not visible in the native terminal UI.
|
||||
Custom integrations can also report state that is not visible in the native terminal UI. They do not need to be built into Herdr or use a recognized agent executable.
|
||||
|
||||
Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Cursor Agent CLI, Grok CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, Kilo Code CLI, MastraCode, and Antigravity CLI panes after a Herdr server restart unless `[session] resume_agents_on_restore = false` disables it.
|
||||
## Integrate your own agent
|
||||
|
||||
Native session restore requires current Herdr integrations: Pi integration version `2`, OMP version `3`, Claude Code version `6`, Codex version `5`, GitHub Copilot CLI version `2`, Devin CLI version `2`, Droid version `2`, Kimi Code CLI version `3`, Qoder CLI version `2`, Cursor Agent CLI version `1`, Grok CLI version `1`, OpenCode version `5`, Kilo Code CLI version `1`, Hermes Agent version `2`, MastraCode version `1`, or Antigravity CLI version `1`. Check installed versions with `herdr integration status`.
|
||||
An agent running in a Herdr pane inherits `HERDR_ENV`, `HERDR_PANE_ID`, `HERDR_BIN_PATH`, and `HERDR_SOCKET_PATH`. If the agent exposes lifecycle hooks, use those hooks to report semantic state through Herdr's CLI:
|
||||
|
||||
```bash
|
||||
"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
|
||||
--source custom:my-agent \
|
||||
--agent my-agent \
|
||||
--state working
|
||||
```
|
||||
|
||||
Report `idle` when the agent is ready for input and `blocked` when it needs a user decision. Use `--message` to describe a block. When the agent exits, release the same source's lifecycle authority:
|
||||
|
||||
```bash
|
||||
"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
|
||||
--source custom:my-agent \
|
||||
--agent my-agent
|
||||
```
|
||||
|
||||
Report only when `HERDR_ENV=1` and the required variables are present. This keeps the integration a no-op outside Herdr. Keep `--source` stable and unique to the integration. If reports can arrive out of order, include a strictly increasing `--seq`; Herdr ignores stale sequence numbers from the same source.
|
||||
|
||||
You can include `--agent-session-id` or `--agent-session-path` with `report-agent`, or use `pane report-agent-session` when session identity changes independently of state. Herdr exposes that reference through its pane and agent APIs. Automatic session restore also requires Herdr to know how to launch that agent and resume the referenced session.
|
||||
|
||||
Use `HERDR_BIN_PATH` and the CLI wrappers for portable integrations. Code that needs direct IPC can send the equivalent `pane.report_agent`, `pane.report_agent_session`, and `pane.release_agent` requests described in the [Socket API](/docs/socket-api/#agent-state-reporting).
|
||||
|
||||
[Prime Agent's built-in Herdr reporter](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts) is a real-world example. It activates only inside Herdr, maps agent events to `working`, `idle`, and `blocked`, preserves report ordering across sessions, and releases authority on exit.
|
||||
|
||||
Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Qwen Code, Cursor Agent CLI, Grok CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, Kilo Code CLI, MastraCode, and Antigravity CLI panes after a Herdr server restart unless `[session] resume_agents_on_restore = false` disables it.
|
||||
|
||||
Native session restore requires current Herdr integrations: Pi integration version `2`, OMP version `3`, Claude Code version `6`, Codex version `5`, GitHub Copilot CLI version `2`, Devin CLI version `2`, Droid version `2`, Kimi Code CLI version `3`, Qoder CLI version `2`, Qwen Code version `1`, Cursor Agent CLI version `1`, Grok CLI version `1`, OpenCode version `5`, Kilo Code CLI version `1`, Hermes Agent version `5`, MastraCode version `1`, or Antigravity CLI version `1`. Check installed versions with `herdr integration status`.
|
||||
|
||||
## Pi
|
||||
|
||||
@@ -148,7 +175,7 @@ herdr integration install devin
|
||||
|
||||
The hook reports native session identity from Devin session, prompt, tool-use, permission, and stop events. Devin state still comes from Herdr's screen manifest and OSC detection because Devin hooks do not emit a reliable state transition after every permission cancellation or user interrupt.
|
||||
|
||||
Herdr uses `~/.config/devin` by default, or `$XDG_CONFIG_HOME/devin` when `XDG_CONFIG_HOME` is set. The Devin config directory must already exist. Install writes `herdr-agent-state.sh` and updates `config.json` with Herdr hook entries. The hook refreshes the session reference while Devin runs. Uninstall removes Herdr entries from `config.json` and deletes the hook script.
|
||||
Herdr uses `~/.config/devin` by default, or `$XDG_CONFIG_HOME/devin` when `XDG_CONFIG_HOME` is set. The Devin config directory must already exist. Install writes `herdr-agent-state.sh` (`herdr-agent-state.ps1` on Windows) and updates `config.json` with Herdr hook entries. The hook refreshes the session reference while Devin runs. Uninstall removes Herdr entries from `config.json` and deletes the hook script.
|
||||
|
||||
Herdr resumes stored Devin sessions with `devin --resume <id>`. Native screen manifest detection remains the state authority whether or not the hook is installed.
|
||||
|
||||
@@ -212,7 +239,7 @@ Install the Hermes Agent plugin:
|
||||
herdr integration install hermes
|
||||
```
|
||||
|
||||
Herdr writes `~/.hermes/plugins/herdr-agent-state/` and enables `herdr-agent-state` in `~/.hermes/config.yaml`. 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`.
|
||||
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`.
|
||||
|
||||
The plugin reports the resumable session id while Hermes runs inside a Herdr pane. Herdr uses screen manifest detection for `working`, `idle`, and `blocked`, and can use the reported session id to resume the pane with `hermes --resume <id>`.
|
||||
|
||||
@@ -232,6 +259,20 @@ Herdr resumes stored Qoder CLI sessions with `qodercli --resume <id>`.
|
||||
|
||||
Native screen manifest detection remains available when the hook is not installed.
|
||||
|
||||
## Qwen Code
|
||||
|
||||
Install the Qwen Code hook:
|
||||
|
||||
```bash
|
||||
herdr integration install qwen
|
||||
```
|
||||
|
||||
The `SessionStart` hook reports only Qwen Code's session identity for native restore. Lifecycle state remains under Herdr's screen manifest detection.
|
||||
|
||||
Herdr uses `~/.qwen` by default, or `QWEN_HOME` when set. The Qwen config directory must already exist. Install writes `hooks/herdr-agent-session.sh` (`hooks/herdr-agent-session.ps1` on Windows) and adds a Herdr entry to `settings.json`. Uninstall removes only the matching entry and managed script.
|
||||
|
||||
Herdr resumes stored Qwen Code sessions with `qwen --resume <id>`.
|
||||
|
||||
## Cursor Agent CLI
|
||||
|
||||
Install the Cursor Agent CLI hook:
|
||||
@@ -242,7 +283,7 @@ herdr integration install cursor
|
||||
|
||||
The hook reports session identity through Cursor's `sessionStart` hook while Cursor Agent CLI runs inside a Herdr pane. Cursor state comes from Herdr's screen manifest detection.
|
||||
|
||||
Herdr uses `~/.cursor` by default, or `CURSOR_CONFIG_DIR` when set. The Cursor config directory must already exist. Install writes `herdr-agent-state.sh` and adds a Herdr `sessionStart` entry to `hooks.json`. Uninstall removes the matching hook entry and deletes the hook script.
|
||||
Herdr uses `~/.cursor` by default, or `CURSOR_CONFIG_DIR` when set. The Cursor config directory must already exist. Install writes `herdr-agent-state.sh` (`herdr-agent-state.ps1` on Windows) and adds a Herdr `sessionStart` entry to `hooks.json`. Uninstall removes the matching hook entry and deletes the hook script.
|
||||
|
||||
After Cursor emits a session start event, Herdr can use the reported session id to resume the pane with `cursor-agent --resume <id>`. The `cursor-agent` command must be on `PATH` when Herdr restores the pane; Herdr does not launch the generic `agent` command.
|
||||
|
||||
@@ -256,7 +297,7 @@ herdr integration install mastracode
|
||||
|
||||
The hook reports MastraCode lifecycle state and thread identity to Herdr for authoritative `idle`, `working`, and `blocked` status and native restore. MastraCode has no screen manifest fallback; state comes from the hook while MastraCode runs inside a Herdr pane.
|
||||
|
||||
Herdr uses `~/.mastracode`. Install writes `hooks/herdr-agent-state.sh` and adds Herdr command entries to `hooks.json`, creating the directory when missing. Uninstall removes the matching hook entries and deletes the hook script.
|
||||
Herdr uses `~/.mastracode`. Install writes `hooks/herdr-agent-state.sh` (`hooks/herdr-agent-state.ps1` on Windows) and adds Herdr command entries to `hooks.json`, creating the directory when missing. Uninstall removes the matching hook entries and deletes the hook script.
|
||||
|
||||
Herdr resumes stored MastraCode threads with `mastracode --thread <id>`.
|
||||
|
||||
@@ -270,7 +311,7 @@ herdr integration install antigravity-cli
|
||||
|
||||
Herdr uses `~/.gemini/config/` by default, or `ANTIGRAVITY_CLI_CONFIG_DIR` when set. This is the directory Antigravity CLI reads global customizations from, and it must already exist. Install writes `hooks/herdr-agent-state.sh` (or `herdr-agent-state.ps1` on Windows) and adds a Herdr-owned `herdr` block to `hooks.json`. Antigravity CLI keys `hooks.json` by hook name, so install rewrites only that block and leaves other named hooks untouched. Uninstall removes the `herdr` block and deletes the hook script.
|
||||
|
||||
This integration is session-only. It reports the conversation the pane is running and does not report agent state, so Herdr keeps deriving working, idle, and blocked from what Antigravity CLI draws on screen.
|
||||
This session-only integration reports the pane's current conversation, but not agent state. Herdr keeps deriving working, idle, and blocked from what Antigravity CLI draws on screen.
|
||||
|
||||
The hook runs on `PreInvocation`, so Herdr learns the conversation once the first prompt is sent. From then on Herdr can resume the pane with `agy --conversation <id>` after a Herdr server restart.
|
||||
|
||||
@@ -284,7 +325,7 @@ herdr integration install grok
|
||||
|
||||
The hook reports session identity through Grok's `SessionStart` hook while Grok CLI runs inside a Herdr pane. Grok state comes from Herdr's screen manifest detection.
|
||||
|
||||
Herdr uses `~/.grok` by default, or `GROK_HOME` when set. The Grok config directory must already exist. Grok merges every `hooks/*.json` file in that directory, so install writes a self-contained `hooks/herdr.json` with the Herdr `SessionStart` entry next to the `hooks/herdr-agent-state.sh` script, and never edits other hook files. Uninstall removes exactly those two Herdr-owned files.
|
||||
Herdr uses `~/.grok` by default, or `GROK_HOME` when set. The Grok config directory must already exist. Grok merges every `hooks/*.json` file in that directory, so install writes a self-contained `hooks/herdr.json` with the Herdr `SessionStart` entry next to `hooks/herdr-agent-state.sh` (`hooks/herdr-agent-state.ps1` on Windows), and never edits other hook files. Uninstall removes exactly those two Herdr-owned files.
|
||||
|
||||
After Grok emits a session start event, Herdr can use the reported session id to resume the pane with `grok --resume <id>`.
|
||||
|
||||
|
||||
@@ -41,9 +41,9 @@ review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
||||
|
||||
利用可能なシェルペインとは、対話シェルのプロンプトに戻っており、フォアグラウンドをシェル自身が所有し、フォアグラウンドのコマンド、エディタ、エージェントが動いていないペインです。`agent start` の前にプロンプトへ戻してください。
|
||||
|
||||
`--kind` は対応済みエージェントとその標準実行ファイルを選びます。対応する kind は `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`maki` です。`--` より後の引数は、その実行ファイルへそのまま渡されます。
|
||||
`--kind` は対応済みエージェントとその標準実行ファイルを選びます。対応する kind は `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`qwen`、`maki` です。`--` より後の引数は、その実行ファイルへそのまま渡されます。
|
||||
|
||||
`agent start` は、同じターミナルで期待したエージェントを検出し、対話入力の準備ができたと Herdr が判断してから返ります。起動待機はデフォルトで 30 秒です。`--timeout` は 3000 より大きく 300000 以下のミリ秒で指定します。
|
||||
成功した `agent start` は、同じターミナルで期待したエージェントを検出し、対話入力の準備ができたと Herdr が判断してから返ります。起動中の検出状態が `blocked` の場合、コマンドは直ちに `agent_not_ready` を返します。名前は `agent read` と `agent send-keys` で引き続き使用でき、検出状態が `idle` になるとプロンプトを送信できるようになります。起動待機はデフォルトで 30 秒です。`--timeout` は 3000 より大きく 300000 以下のミリ秒で指定します。
|
||||
|
||||
```bash
|
||||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
@@ -69,11 +69,11 @@ herdr agent rename w1:p2 reviewer
|
||||
| エージェントの対話 UI にキーを送る | `agent send-keys` |
|
||||
| エージェントのライフサイクル状態を待つ | `agent wait` |
|
||||
|
||||
`agent prompt` は文字列とエンコード済み Enter を送信し、ターミナルの現在の bracketed paste モードを尊重します。working 中のエージェントにも送信できます。`esc`、`up`、`enter`、`ctrl+c` のような操作には `agent send-keys` を使います。`escape` も `esc` のエイリアスとして使えます。意図的に生のターミナルを操作したい場合は、ペイン入力コマンドを使ってください。
|
||||
`agent prompt` はテキストを送信し、短い遅延の後にエンコード済み Enter を送信します。ターミナルの現在の bracketed paste モードを尊重します。working 中のエージェントにも送信できます。エージェントがすでに `blocked` の場合は、ターミナル入力を送信せずに `agent_blocked` を返します。ダイアログを確認し、意図した応答には `agent send-keys` を使ってください。`esc`、`up`、`enter`、`ctrl+c` のような操作には `agent send-keys` を使います。`escape` も `esc` のエイリアスとして使えます。意図的に生のターミナルを操作したい場合は、ペイン入力コマンドを使ってください。
|
||||
|
||||
ペイン入力は、現在のプロセスに関係なくターミナルを指定します。エージェント入力はライブエージェントを解決し、そのエージェントがペインを制御しなくなっていれば操作を拒否します。
|
||||
|
||||
`agent prompt --wait` はプロンプトをすぐ送信します。エージェントが non-working 状態から始まる場合、Herdr はまず 5 秒以内にライフサイクル変化が観測されることを要求します。状態シーケンスが進まなければ、無期限に待たず `agent_prompt_stalled` を返します。呼び出し側の `--timeout` が 5 秒以下なら、通常の `timeout` エラーを返します。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。エージェントがすでに working の場合、進行中ターンの完了が待機を満たすことがあります。単独の `agent wait` は現在のエージェントを監視し、すでに状態が一致していれば即座に返ります。どちらもデフォルトでは `idle`、`done`、`blocked` を待ちます。複数の正確な状態を許可するには、`--until idle --until done` のように `--until` を繰り返します。`unknown` が必要な場合は `--until unknown` を明示してください。`agent prompt` では `--until` に `--wait` が必要です。
|
||||
`agent prompt --wait` は、エージェントがすでに `blocked` でない限り、プロンプトをすぐ送信します。すでに `blocked` の場合は待機を開始せずに `agent_blocked` を返します。受け付けたプロンプトが別の non-working 状態から始まる場合、Herdr はまず 5 秒以内にライフサイクル変化が観測されることを要求します。状態シーケンスが進まなければ、無期限に待たず `agent_prompt_stalled` を返します。呼び出し側の `--timeout` が 5 秒以下なら、通常の `timeout` エラーを返します。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。エージェントがすでに working の場合、進行中ターンの完了が待機を満たすことがあります。単独の `agent wait` は現在のエージェントを監視し、すでに状態が一致していれば即座に返ります。どちらもデフォルトでは `idle`、`done`、`blocked` を待ちます。複数の正確な状態を許可するには、`--until idle --until done` のように `--until` を繰り返します。`unknown` が必要な場合は `--until unknown` を明示してください。`agent prompt` では `--until` に `--wait` が必要です。
|
||||
|
||||
`idle` は、エージェントが入力待ちで、そのタブがフォーカス中の Herdr UI ですでに表示済みであることを示します。`done` は同じ基礎的な idle 状態ですが、バックグラウンド作業が完了してから、そのタブをフォーカスするか `pane focus` / `agent focus` で対象にするまで使われます。CLI で読み取るだけでは表示済みになりません。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するもののライフサイクルを確実に分類できない状態で、成功完了を意味しません。違いが重要なら正確な `--until` を指定してください。
|
||||
|
||||
|
||||
@@ -20,6 +20,7 @@ Herdr は複数のコーディングエージェントを同時に動かすた
|
||||
| Kimi Code CLI | インストール時はライフサイクルフック。それ以外はスクリーンマニフェスト | 状態とセッション |
|
||||
| Hermes Agent | スクリーンマニフェスト | セッション |
|
||||
| Qoder CLI | スクリーンマニフェスト | セッション |
|
||||
| Qwen Code | スクリーンマニフェスト | セッション |
|
||||
| Droid | スクリーンマニフェスト | セッション |
|
||||
| OpenCode | インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト | 状態とセッション |
|
||||
| Kilo Code CLI | インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト | 状態とセッション |
|
||||
@@ -103,7 +104,7 @@ herdr integration install claude
|
||||
herdr integration status
|
||||
```
|
||||
|
||||
対応エージェントごとに、インテグレーションの名前と挙動は異なります。エージェント別の詳細と完全なインストール一覧は[インテグレーション](/ja/docs/integrations/)を参照してください。
|
||||
対応エージェントごとに、インテグレーションの名前と挙動は異なります。エージェント別の詳細と完全なインストール一覧は[インテグレーション](/ja/docs/integrations/)を参照してください。エージェントを開発している場合は、[カスタムインテグレーションガイド](/ja/docs/integrations/#独自エージェントを統合する)で、Herdr にネイティブサポートを追加せずにライフサイクル状態を報告する方法を確認できます。
|
||||
|
||||
## カスタムエージェントラベル
|
||||
|
||||
|
||||
@@ -285,11 +285,11 @@ herdr agent explain --file PATH --agent LABEL [--json|--verbose]
|
||||
|
||||
エージェントターゲットは、一意なライブエージェント名、または現在そのエージェントをホストしているペイン ID です。ターミナル ID とエージェント kind のラベルだけでは指定できません。`agent start` で起動するエージェントには名前が必須で、手動で起動したエージェントは名前なしのままペイン ID で指定します。
|
||||
|
||||
`agent start` は既存の利用可能なシェルペインを起動対象にします。対話シェル自身がフォアグラウンドを所有し、フォアグラウンドのコマンド、エディタ、エージェントが動いていない必要があります。トポロジーは別に作成します。名前はライブエージェント間で一意で、`[a-z][a-z0-9_-]{0,31}` に一致する必要があります。対応する kind は `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`maki` です。名前は現在のペイン占有者に属し、そのエージェントの終了、release、置換で消えます。一時的に検出できないだけでは消えません。
|
||||
`agent start` は既存の利用可能なシェルペインを起動対象にします。対話シェル自身がフォアグラウンドを所有し、フォアグラウンドのコマンド、エディタ、エージェントが動いていない必要があります。トポロジーは別に作成します。名前はライブエージェント間で一意で、`[a-z][a-z0-9_-]{0,31}` に一致する必要があります。対応する kind は `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`qwen`、`maki` です。名前は現在のペイン占有者に属し、そのエージェントの終了、release、置換で消えます。一時的に検出できないだけでは消えません。
|
||||
|
||||
start は、期待したエージェントが同じターミナルを所有し、対話入力の準備ができてから返ります。デフォルトの起動タイムアウトは 30000 ミリ秒で、明示する値は 3000 より大きく 300000 以下でなければなりません。
|
||||
成功した start は、期待したエージェントが同じターミナルを所有し、対話入力の準備ができてから返ります。起動中の検出状態が `blocked` の場合、コマンドは直ちに `agent_not_ready` を返します。名前は `agent read` と `agent send-keys` で引き続き使用でき、検出状態が `idle` になるとプロンプトを送信できるようになります。デフォルトの起動タイムアウトは 30000 ミリ秒で、明示する値は 3000 より大きく 300000 以下でなければなりません。
|
||||
|
||||
`agent prompt` は現在の bracketed paste モードを尊重し、working 中でもテキストとエンコード済み Enter をアトミックに送信します。`--wait` を使う場合、non-working 状態から送信したプロンプトは 5 秒以内に観測可能なライフサイクル変化を起こす必要があり、変化がなければ Herdr は `agent_prompt_stalled` を返します。呼び出し側のタイムアウトが 5 秒以下なら、通常の `timeout` エラーを維持します。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。すでに working の場合、進行中ターンの完了が待機を満たすことがあります。`--until` は一致状態を絞り込み、`--wait` なしでは拒否されます。単独の `agent wait` は現在の状態が一致すれば即座に返ります。どちらもデフォルトは `idle`、`done`、`blocked` です。
|
||||
`agent prompt` は現在の bracketed paste モードを尊重し、working 中でもテキストを送信してから短い遅延の後にエンコード済み Enter を送信します。エージェントがすでに `blocked` の場合は、入力を送信せずに `agent_blocked` を返します。`--wait` を使う場合、別の non-working 状態から受け付けたプロンプトは 5 秒以内に観測可能なライフサイクル変化を起こす必要があり、変化がなければ Herdr は `agent_prompt_stalled` を返します。呼び出し側のタイムアウトが 5 秒以下なら、通常の `timeout` エラーを維持します。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。すでに working の場合、進行中ターンの完了が待機を満たすことがあります。`--until` は一致状態を絞り込み、`--wait` なしでは拒否されます。単独の `agent wait` は現在の状態が一致すれば即座に返ります。どちらもデフォルトは `idle`、`done`、`blocked` です。
|
||||
|
||||
`idle` は入力待ちで、そのタブがフォーカス中の Herdr UI ですでに表示済みの状態です。`done` は同じ基礎的な idle 状態ですが、表示していないバックグラウンド作業が完了したときに使われます。そのタブをフォーカスするか `pane focus` / `agent focus` で対象にすると表示済みになりますが、CLI で読み取るだけでは変わりません。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するものの確実に分類できない状態で、作業の成功を意味しません。
|
||||
|
||||
@@ -308,7 +308,7 @@ herdr terminal title clear
|
||||
```
|
||||
|
||||
ダイレクトアタッチからは `ctrl+b q` でデタッチします。リテラルの `ctrl+b` は `ctrl+b ctrl+b` で送ります。
|
||||
`terminal title clear` は Herdr のデフォルトの外側ターミナルウィンドウタイトルを復元します。
|
||||
`terminal title clear` は外側ターミナルウィンドウタイトルを `ui.window_title` に戻します。
|
||||
|
||||
## 出力待機
|
||||
|
||||
@@ -340,6 +340,7 @@ herdr integration install kilo
|
||||
herdr integration install hermes
|
||||
herdr integration install mastracode
|
||||
herdr integration install qodercli
|
||||
herdr integration install qwen
|
||||
herdr integration install cursor
|
||||
herdr integration uninstall pi
|
||||
herdr integration uninstall omp
|
||||
@@ -354,6 +355,7 @@ herdr integration uninstall kilo
|
||||
herdr integration uninstall hermes
|
||||
herdr integration uninstall mastracode
|
||||
herdr integration uninstall qodercli
|
||||
herdr integration uninstall qwen
|
||||
herdr integration uninstall cursor
|
||||
herdr integration status [--outdated-only]
|
||||
```
|
||||
|
||||
@@ -50,6 +50,18 @@ Herdr のグローバルメニューを開いて `reload config` を選ぶこと
|
||||
|
||||
リロードは、ペインを再起動せずにほとんどの UI 設定を適用します。起動時のみの設定には引き続き再起動が必要です。
|
||||
|
||||
## ヘッドレスターミナルのサイズ
|
||||
|
||||
クライアントが接続されていない場合、サーバーはレイアウトと新しく作成されるペインに 120×40 の仮想ターミナルを使います。ヘッドレスオーケストレーション用のフォールバックは次のように変更できます:
|
||||
|
||||
```toml
|
||||
[server]
|
||||
headless_cols = 160
|
||||
headless_rows = 50
|
||||
```
|
||||
|
||||
クライアントが接続されている間は、そのクライアントが共有ランタイムのサイズを決定します。切断後、既存のペイン PTY は最後に接続されていたときのサイズを保ち、新しいヘッドレスレイアウトには設定したフォールバックが使われます。
|
||||
|
||||
## ターミナルのデフォルト
|
||||
|
||||
新しく作成される対話型ペインに Herdr が使う実行ファイルを設定します:
|
||||
@@ -98,14 +110,14 @@ worktree チェックアウトの削除は明示的に行います。グルー
|
||||
|
||||
## リモートアタッチ
|
||||
|
||||
リモートアタッチは、デフォルトで一時的なキープアライブと接続再利用のフォールバックを使って SSH 接続を管理します。
|
||||
リモートアタッチは、デフォルトで一時的なキープアライブと、対応する環境では接続再利用を使って SSH 接続を管理します。
|
||||
|
||||
```toml
|
||||
[remote]
|
||||
manage_ssh_config = true
|
||||
```
|
||||
|
||||
有効な場合、`herdr --remote` は最初に `~/.ssh/config` と `/etc/ssh/ssh_config` を取り込み、その後にフォールバックの `ServerAliveInterval` と `ServerAliveCountMax` の値を加えた、プライベートな一時 SSH 設定を書き込みます。ユーザー自身のキープアライブ設定が優先されます。Herdr は、最初に認証した接続を再利用するため、アタッチごとにプライベートな OpenSSH コントロールソケットも使います。Herdr が生成した設定やコントロールソケットを使わず、通常の `ssh` でリモートアタッチを実行するには `manage_ssh_config = false` を設定してください。
|
||||
有効な場合、`herdr --remote` は最初にユーザーとシステムの SSH 設定を取り込み、その後にフォールバックの `ServerAliveInterval` と `ServerAliveCountMax` の値を加えた、プライベートな一時 SSH 設定を書き込みます。ユーザー自身のキープアライブ設定が優先されます。Linux と macOS クライアントは、最初に認証した接続を再利用するため、アタッチごとにプライベートな OpenSSH コントロールソケットも使います。Windows OpenSSH ではこの接続再利用を使いません。Herdr が生成した設定やコントロールソケットを使わず、通常の `ssh` でリモートアタッチを実行するには `manage_ssh_config = false` を設定してください。
|
||||
|
||||
## キーバインド
|
||||
|
||||
@@ -137,7 +149,15 @@ split_horizontal = "prefix+minus"
|
||||
next_tab = ["prefix+n", "ctrl+alt+]"]
|
||||
```
|
||||
|
||||
任意のアクションはデフォルトでは未設定です。プレフィックスモードの挙動には `prefix+` でバインドし、意図的に直接ショートカットにする場合は明示的な修飾キーコードを使ってください。
|
||||
任意のアクションはデフォルトでは未設定です。プレフィックスモードの挙動には `prefix+` でバインドし、意図的に直接ショートカットにする場合は明示的な修飾キーコードを使ってください。たとえば、リサイズモードに入らず tmux のように 1 回のキー操作でペインをリサイズできます:
|
||||
|
||||
```toml
|
||||
[keys]
|
||||
resize_pane_left = "ctrl+shift+alt+left"
|
||||
resize_pane_down = "ctrl+shift+alt+down"
|
||||
resize_pane_up = "ctrl+shift+alt+up"
|
||||
resize_pane_right = "ctrl+shift+alt+right"
|
||||
```
|
||||
|
||||
キー文字列には、通常のキー、`ctrl+a`、`shift+n`、`alt+1`、`cmd+k` のような修飾キーの組み合わせ、`enter`、`tab`、`esc`、`left`、`right`、`up`、`down` のような特殊キーが使えます。`minus`、`comma`、`ampersand`、`plus`、`backtick` のような名前付き記号も使えます。`n` のような通常の印字可能キーの直接バインドは入力を妨げるため危険です。意図的に直接バインドするのでなければ `prefix+n` を使ってください。`navigate_workspace_*` と `navigate_pane_*` のフィールドはナビゲートモード専用で、`j` や `k` のような通常のキーを使えます。これらには `prefix+`、`esc`、`enter`、`tab`、`shift+tab`、`left`、`right`、修飾なしの `1` から `9` は使えません。左右の矢印キーは、左ペインと右ペインへのナビゲーションの恒久的なエイリアスです。これらのナビゲートモードショートカットは、`focus_pane_down = "prefix+j"` のような一般アクションのバインドから独立しています。両方に同じキーが使われている場合、ナビゲートモードが開いている間はナビゲートモードのショートカットが優先されます。Alt、Cmd/Super、修飾キー付き記号は、ターミナルと tmux の設定に依存します。
|
||||
|
||||
@@ -238,6 +258,9 @@ dark_name = "catppuccin"
|
||||
|
||||
```toml
|
||||
[theme.custom]
|
||||
sidebar_bg = "#181825"
|
||||
active_row_bg = "#1e1e2e"
|
||||
selection_bg = "#313244"
|
||||
panel_bg = "reset"
|
||||
accent = "#a6e3a1"
|
||||
green = "#a6e3a1"
|
||||
@@ -246,12 +269,60 @@ red = "#f38ba8"
|
||||
yellow = "#f9e2af"
|
||||
```
|
||||
|
||||
`sidebar_bg` を使うと、デスクトップのサイドバーだけに背景色を設定できます。省略した場合、サイドバーはホストターミナルの背景を使います。`active_row_bg` は、区切り線やスクロールバートラックに影響を与えず、アクティブな Space とフォーカス中の Agent 行の背景色を変更します。`selection_bg` は、サイドバーの Navigate モードのカーソル行の背景色を変更します。
|
||||
|
||||
色の値には、hex、名前付きの色、`rgb(r,g,b)`、または `reset`、`default`、`none`、`transparent` のようなリセットエイリアスが使えます。
|
||||
|
||||
## UI とサイドバー
|
||||
|
||||
サイドバーは Herdr のメインダッシュボードです。サイズ、折りたたみモード、Agent パネルの並び順、マウスの挙動、ペインの境界線、その他の表示設定については、[設定リファレンス](/docs/config-reference/)で `ui.` を検索してください。
|
||||
|
||||
`[ui]` の `tab_bar_position = "bottom"` を設定すると、デスクトップのタブ行をターミナルペインの下に配置できます。Prefix、Navigate、Copy、Resize の各モードバーは、表示中だけ下部のタブ行を置き換えます。デフォルトは `"top"` です。
|
||||
|
||||
タブ行の右端に、tmux のような順序付きステータス領域を設定できます:
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
tab_bar_right = [
|
||||
{ type = "zoom" },
|
||||
{ type = "hostname" },
|
||||
{ type = "datetime", format = "%H:%M" },
|
||||
{ type = "text", text = "prod" },
|
||||
{ type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
|
||||
]
|
||||
tab_bar_right_separator = " · "
|
||||
```
|
||||
|
||||
ステータス領域はデフォルトでは空です。`zoom` を追加すると、アクティブなタブがズーム中のとき固定の `ZOOM` ピルが表示されます。各タブの既存の `Z` マーカーとは独立しています。`hostname`、`datetime`、`command` は Herdr サーバー上で解決されるため、`herdr --remote` ではリモートマシンの値が表示されます。日時エントリは `strftime` 形式を使います。`%z` や `%s` のように UTC オフセットまたは Unix タイムスタンプを必要とする指定子は、値がサーバーローカルの壁時計時刻であるため拒否されます。
|
||||
|
||||
コマンドエントリはすぐに実行され、その後 `interval_seconds` ごとに更新されます。描画をブロックせず、前回の実行と重複しません。間隔は 1〜31,536,000 秒、タイムアウトは 1〜3,600 秒です。Herdr は成功した出力の最終行を使い、失敗、空の出力、`timeout_seconds` 経過後には値を消去します。カスタムコマンドキーバインドと同じアクティブなワークスペース、タブ、ペイン、ソケット、バイナリ、作業ディレクトリのコンテキストが提供されます。コマンドは Linux、macOS、Windows で利用でき、Linux と macOS では `/bin/sh -lc`、Windows では `cmd.exe /d /c` が使われます。
|
||||
|
||||
区切り文字は、表示されているエントリの間にだけ挿入されます。直接連結するには `tab_bar_right_separator = ""` を設定します。タブ行が狭い場合、ステータス領域全体がタブとそのコントロールに場所を譲ります。
|
||||
|
||||
### 外側のターミナルのウィンドウタイトル
|
||||
|
||||
Herdr はペイン内のターミナルをエミュレートするため、ペイン内で書き込まれた `OSC 0`/`OSC 2` のタイトルは Herdr で止まります。Herdr は自身が動作しているターミナルに独自のタイトルを書き込み、ウィンドウマネージャーやターミナルのタブバーはこれを読み取ります:
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
window_title = "{hostname}: {workspace}"
|
||||
```
|
||||
|
||||
トークンは `{hostname}`、`{workspace}`、`{tab}`、`{pane}`(フォーカス中のペインの手動名)、`{terminal_title}`(フォーカス中のペイン自身のターミナルタイトルからスピナーを取り除いたもの)です。波括弧そのものを書くには `{{` と `}}` を使います。値のないトークンは空になります。
|
||||
|
||||
タイトルは Herdr サーバー上で生成されるため、`herdr --remote` で接続した場合や SSH 越しに `herdr` を実行した場合でも、`{hostname}` はペインが動作しているマシンを指します。外側のターミナルのタイトルに触れないようにするには `window_title = ""` を設定します。
|
||||
|
||||
`client.window_title.set` は設定されたタイトルを上書きし、`client.window_title.clear` がそれを戻します。
|
||||
|
||||
Agent の状態は、デフォルトではコンパクトな色付きドットで表示されます。blocked、working、done、idle、unknown を色だけでなく形でも区別するには、設定画面で **distinct symbols** を選ぶか、次のように設定します:
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
status_indicators = "symbols"
|
||||
```
|
||||
|
||||
これらの記号は静的なので、このオプションでスピナーアニメーションが有効になることはありません。
|
||||
|
||||
### サイドバーの行レイアウト
|
||||
|
||||
展開されたデスクトップサイドバーでは、`rows` の各内側の配列が 1 行として描画されます。完全なデフォルトレイアウトは次のとおりです:
|
||||
@@ -367,6 +438,8 @@ position = "bottom-right"
|
||||
|
||||
アプリ内トーストには `herdr`、SSH 越しでも使いやすい外側のターミナル通知には `terminal`、ローカル OS の通知サービスには `system`、ポップアップを無効にするには `off` を選びます。Herdr はアクティブなタブのポップアップを抑制します。位置、遅延の挙動、クリップボードのフィードバック設定については、[設定リファレンス](/docs/config-reference/)で `ui.toast` を検索してください。
|
||||
|
||||
macOS では、`system` は最初に `terminal-notifier` を試し、利用できない場合や失敗した場合は `/usr/bin/osascript` にフォールバックします。このフォールバックは通知センターで Script Editor として表示され、ホストターミナルをアクティブにできません。`brew install terminal-notifier` で `terminal-notifier` をインストールできます。対応するターミナルを Herdr が検出できた場合、通知のクリック時にそのターミナルアプリをアクティブにできます。または、`terminal` を選んで対応する外側のターミナルに通知を送信させてください。
|
||||
|
||||
## サウンド
|
||||
|
||||
サウンド通知はローカルの Herdr クライアントで再生されます。カスタムサウンドは mp3 ファイルでなければなりません。相対パスは設定ファイルのディレクトリから解決されます。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: インテグレーション
|
||||
description: Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Cursor Agent CLI、MastraCode、Antigravity CLI、Grok CLI 向けの Herdr インテグレーションをインストールします。
|
||||
description: Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Qwen Code、Cursor Agent CLI、MastraCode、Antigravity CLI、Grok CLI 向けの Herdr インテグレーションをインストールします。
|
||||
---
|
||||
|
||||
Herdr は対応エージェントを自動的に検出します。公式インテグレーションは、復元のためのネイティブセッション識別、ライフサイクル状態の報告、またはその両方を追加できます。
|
||||
@@ -25,6 +25,7 @@ herdr integration install kilo
|
||||
herdr integration install hermes
|
||||
herdr integration install mastracode
|
||||
herdr integration install qodercli
|
||||
herdr integration install qwen
|
||||
herdr integration install cursor
|
||||
herdr integration install antigravity-cli
|
||||
herdr integration install grok
|
||||
@@ -46,6 +47,7 @@ herdr integration uninstall kilo
|
||||
herdr integration uninstall hermes
|
||||
herdr integration uninstall mastracode
|
||||
herdr integration uninstall qodercli
|
||||
herdr integration uninstall qwen
|
||||
herdr integration uninstall cursor
|
||||
herdr integration uninstall antigravity-cli
|
||||
herdr integration uninstall grok
|
||||
@@ -58,13 +60,40 @@ Herdr はインテグレーションを 2 つの異なる方法で使います:
|
||||
| インテグレーションの種類 | エージェント | 効果 |
|
||||
| --- | --- | --- |
|
||||
| ライフサイクル権威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、MastraCode | インストールされ、そのペインについて能動的に報告している間は、フックまたはプラグインのイベントが `idle`、`working`、`blocked` を決定します。同じライフサイクル権威に対して、Herdr はスクリーンマニフェストのフォールバックを併用しません。 |
|
||||
| セッション識別 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Cursor Agent CLI、Hermes Agent、Antigravity CLI、Grok CLI | インテグレーションは復元用のネイティブセッション参照を報告します。状態は引き続き Herdr のスクリーンマニフェスト検出から得られます。 |
|
||||
| セッション識別 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Qwen Code、Cursor Agent CLI、Hermes Agent、Antigravity CLI、Grok CLI | インテグレーションは復元用のネイティブセッション参照を報告します。状態は引き続き Herdr のスクリーンマニフェスト検出から得られます。 |
|
||||
|
||||
カスタムソケットインテグレーションも、ネイティブのターミナル UI では見えない状態を定義する場合に状態を報告できます。
|
||||
カスタムインテグレーションも、ネイティブのターミナル UI では見えない状態を定義する場合に状態を報告できます。Herdr への組み込みや、認識済みのエージェント実行ファイルは必要ありません。
|
||||
|
||||
一部のインテグレーションは、エージェントのネイティブセッション参照を報告します。Herdr は公式のセッション参照を使って、`[session] resume_agents_on_restore = false` で無効化されていない限り、Herdr サーバーの再起動後に Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、Grok CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode、Antigravity CLI のペインを resume します。
|
||||
## 独自エージェントを統合する
|
||||
|
||||
エージェントネイティブのセッション復元には最新の Herdr インテグレーションが必要です: Pi インテグレーションはバージョン `2`、OMP は `3`、Claude Code は `6`、Codex は `5`、GitHub Copilot CLI は `2`、Devin CLI は `2`、Droid は `2`、Kimi Code CLI は `3`、Qoder CLI は `2`、Cursor Agent CLI は `1`、Grok CLI は `1`、OpenCode は `5`、Kilo Code CLI は `1`、Hermes Agent は `2`、MastraCode は `1`、Antigravity CLI は `1` です。インストール済みバージョンは `herdr integration status` で確認してください。
|
||||
Herdr ペイン内で動くエージェントは、`HERDR_ENV`、`HERDR_PANE_ID`、`HERDR_BIN_PATH`、`HERDR_SOCKET_PATH` を継承します。エージェントがライフサイクルフックを提供している場合は、そのフックから Herdr の CLI を使ってセマンティックな状態を報告します:
|
||||
|
||||
```bash
|
||||
"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
|
||||
--source custom:my-agent \
|
||||
--agent my-agent \
|
||||
--state working
|
||||
```
|
||||
|
||||
エージェントが入力待ちになったら `idle`、ユーザーの判断が必要になったら `blocked` を報告します。ブロックの説明には `--message` を使います。エージェントの終了時には、同じ source のライフサイクル権威を解放します:
|
||||
|
||||
```bash
|
||||
"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
|
||||
--source custom:my-agent \
|
||||
--agent my-agent
|
||||
```
|
||||
|
||||
Herdr の外では何もしないように、`HERDR_ENV=1` で必要な変数が存在するときだけ報告してください。`--source` はインテグレーションごとに一意かつ固定にします。報告が順不同で届く可能性がある場合は、単調増加する `--seq` を含めてください。Herdr は同じ source から届いた古いシーケンス番号を無視します。
|
||||
|
||||
`report-agent` に `--agent-session-id` または `--agent-session-path` を含めることも、セッション識別が状態とは独立して変わる場合に `pane report-agent-session` を使うこともできます。Herdr はその参照をペイン API とエージェント API で公開します。セッションの自動復元には、それに加えて、そのエージェントの起動方法と参照先セッションの再開方法を Herdr が把握している必要があります。
|
||||
|
||||
移植可能なインテグレーションには `HERDR_BIN_PATH` と CLI ラッパーを使ってください。直接 IPC が必要なコードでは、[Socket API](/ja/docs/socket-api/) に記載された同等の `pane.report_agent`、`pane.report_agent_session`、`pane.release_agent` リクエストを送信できます。
|
||||
|
||||
[Prime Agent の組み込み Herdr レポーター](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts)は実際の実装例です。Herdr 内でのみ有効になり、エージェントイベントを `working`、`idle`、`blocked` に対応付け、セッションをまたいで報告順序を維持し、終了時に権威を解放します。
|
||||
|
||||
一部のインテグレーションは、エージェントのネイティブセッション参照を報告します。Herdr は公式のセッション参照を使って、`[session] resume_agents_on_restore = false` で無効化されていない限り、Herdr サーバーの再起動後に Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Qwen Code、Cursor Agent CLI、Grok CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode、Antigravity CLI のペインを resume します。
|
||||
|
||||
エージェントネイティブのセッション復元には最新の Herdr インテグレーションが必要です: Pi インテグレーションはバージョン `2`、OMP は `3`、Claude Code は `6`、Codex は `5`、GitHub Copilot CLI は `2`、Devin CLI は `2`、Droid は `2`、Kimi Code CLI は `3`、Qoder CLI は `2`、Qwen Code は `1`、Cursor Agent CLI は `1`、Grok CLI は `1`、OpenCode は `5`、Kilo Code CLI は `1`、Hermes Agent は `5`、MastraCode は `1`、Antigravity CLI は `1` です。インストール済みバージョンは `herdr integration status` で確認してください。
|
||||
|
||||
## Pi
|
||||
|
||||
@@ -148,7 +177,7 @@ herdr integration install devin
|
||||
|
||||
このフックは、Devin のセッション、プロンプト、ツール使用、許可、停止の各イベントからネイティブセッション識別を報告します。Devin のフックはすべての許可キャンセルやユーザー割り込みの後に信頼できる状態遷移を発行しないため、Devin の状態は引き続き Herdr のスクリーンマニフェストと OSC 検出から得られます。
|
||||
|
||||
Herdr はデフォルトで `~/.config/devin` を使い、`XDG_CONFIG_HOME` が設定されていれば `$XDG_CONFIG_HOME/devin` を使います。Devin の設定ディレクトリはあらかじめ存在している必要があります。インストールは `herdr-agent-state.sh` を書き込み、`config.json` に Herdr のフックエントリを追加します。フックは Devin の実行中にセッション参照を更新します。アンインストールは `config.json` から Herdr のエントリを削除し、フックスクリプトを削除します。
|
||||
Herdr はデフォルトで `~/.config/devin` を使い、`XDG_CONFIG_HOME` が設定されていれば `$XDG_CONFIG_HOME/devin` を使います。Devin の設定ディレクトリはあらかじめ存在している必要があります。インストールは `herdr-agent-state.sh`（Windows では `herdr-agent-state.ps1`）を書き込み、`config.json` に Herdr のフックエントリを追加します。フックは Devin の実行中にセッション参照を更新します。アンインストールは `config.json` から Herdr のエントリを削除し、フックスクリプトを削除します。
|
||||
|
||||
Herdr は保存された Devin セッションを `devin --resume <id>` で resume します。フックのインストール有無にかかわらず、スクリーンマニフェスト検出が状態の権威のままです。
|
||||
|
||||
@@ -212,7 +241,7 @@ Hermes Agent プラグインをインストールします:
|
||||
herdr integration install hermes
|
||||
```
|
||||
|
||||
Herdr は `~/.hermes/plugins/herdr-agent-state/` を書き込み、`~/.hermes/config.yaml` で `herdr-agent-state` を有効にします。Hermes の設定ディレクトリはあらかじめ存在している必要があります。プラグインを読み込ませるため、インストール後に Hermes を再起動してください。アンインストールはプラグインディレクトリを削除し、`plugins.enabled` から `herdr-agent-state` を削除します。
|
||||
Herdr は Hermes ホームディレクトリ内の `plugins/herdr-agent-state/` に書き込み、その `config.yaml` で `herdr-agent-state` を有効にします。`HERMES_HOME` のデフォルトは Unix では `~/.hermes`、Windows では `%LOCALAPPDATA%\hermes` です。Hermes の設定ディレクトリはあらかじめ存在している必要があります。プラグインを読み込ませるため、インストール後に Hermes を再起動してください。アンインストールはプラグインディレクトリを削除し、`plugins.enabled` から `herdr-agent-state` を削除します。
|
||||
|
||||
このプラグインは、Hermes が Herdr のペイン内で動いている間、resume 可能なセッション id を報告します。Herdr は `working`、`idle`、`blocked` にスクリーンマニフェスト検出を使い、報告されたセッション id で `hermes --resume <id>` としてペインを resume できます。
|
||||
|
||||
@@ -232,6 +261,20 @@ Herdr は保存された Qoder CLI セッションを `qodercli --resume <id>`
|
||||
|
||||
フックがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。
|
||||
|
||||
## Qwen Code
|
||||
|
||||
Qwen Code フックをインストールします:
|
||||
|
||||
```bash
|
||||
herdr integration install qwen
|
||||
```
|
||||
|
||||
`SessionStart` フックはネイティブ復元用のセッション識別だけを報告します。ライフサイクル状態は引き続き Herdr のスクリーンマニフェスト検出が決定します。
|
||||
|
||||
Herdr はデフォルトで `~/.qwen` を使い、`QWEN_HOME` が設定されていればそちらを使います。Qwen の設定ディレクトリはあらかじめ存在している必要があります。インストールは `hooks/herdr-agent-session.sh`（Windows では `hooks/herdr-agent-session.ps1`）を書き込み、`settings.json` に Herdr エントリを追加します。アンインストールは一致するエントリと管理対象スクリプトだけを削除します。
|
||||
|
||||
Herdr は保存された Qwen Code セッションを `qwen --resume <id>` で resume します。
|
||||
|
||||
## Cursor Agent CLI
|
||||
|
||||
Cursor Agent CLI フックをインストールします:
|
||||
@@ -242,7 +285,7 @@ herdr integration install cursor
|
||||
|
||||
このフックは、Cursor Agent CLI が Herdr のペイン内で動いている間、Cursor の `sessionStart` フックを通じてセッション識別を報告します。Cursor の状態は Herdr のスクリーンマニフェスト検出から得られます。
|
||||
|
||||
Herdr はデフォルトで `~/.cursor` を使い、`CURSOR_CONFIG_DIR` が設定されていればそちらを使います。Cursor の設定ディレクトリはあらかじめ存在している必要があります。インストールは `herdr-agent-state.sh` を書き込み、`hooks.json` に Herdr の `sessionStart` エントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
|
||||
Herdr はデフォルトで `~/.cursor` を使い、`CURSOR_CONFIG_DIR` が設定されていればそちらを使います。Cursor の設定ディレクトリはあらかじめ存在している必要があります。インストールは `herdr-agent-state.sh`（Windows では `herdr-agent-state.ps1`）を書き込み、`hooks.json` に Herdr の `sessionStart` エントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
|
||||
|
||||
Cursor がセッション開始イベントを発行した後、Herdr は報告されたセッション id を使って `cursor-agent --resume <id>` でペインを resume できます。Herdr がペインを復元するとき、`cursor-agent` コマンドが `PATH` にある必要があります。Herdr は汎用の `agent` コマンドを起動しません。
|
||||
|
||||
@@ -256,7 +299,7 @@ herdr integration install mastracode
|
||||
|
||||
このフックは、MastraCode のライフサイクル状態とスレッド識別を Herdr に報告し、権威ある `idle`、`working`、`blocked` 状態とネイティブ復元を提供します。MastraCode にはスクリーンマニフェストのフォールバックはありません。MastraCode が Herdr ペイン内で動いている間、状態はフックから得られます。
|
||||
|
||||
Herdr は `~/.mastracode` を使います。インストールは `hooks/herdr-agent-state.sh` を書き込み、`hooks.json` に Herdr のコマンドエントリを追加します。ディレクトリがなければ作成します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
|
||||
Herdr は `~/.mastracode` を使います。インストールは `hooks/herdr-agent-state.sh`（Windows では `hooks/herdr-agent-state.ps1`）を書き込み、`hooks.json` に Herdr のコマンドエントリを追加します。ディレクトリがなければ作成します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。
|
||||
|
||||
Herdr は保存された MastraCode スレッドを `mastracode --thread <id>` で resume します。
|
||||
|
||||
@@ -284,7 +327,7 @@ herdr integration install grok
|
||||
|
||||
このフックは、Grok CLI が Herdr のペイン内で動いている間、Grok の `SessionStart` フックを通じてセッション識別を報告します。Grok の状態は Herdr のスクリーンマニフェスト検出から得られます。
|
||||
|
||||
Herdr はデフォルトで `~/.grok` を使い、`GROK_HOME` が設定されていればそちらを使います。Grok の設定ディレクトリはあらかじめ存在している必要があります。Grok はそのディレクトリ内のすべての `hooks/*.json` ファイルを統合するため、インストールは Herdr の `SessionStart` エントリだけを含む `hooks/herdr.json` と `hooks/herdr-agent-state.sh` を書き込み、ほかのフックファイルには触れません。アンインストールは Herdr 所有のこの 2 ファイルだけを削除します。
|
||||
Herdr はデフォルトで `~/.grok` を使い、`GROK_HOME` が設定されていればそちらを使います。Grok の設定ディレクトリはあらかじめ存在している必要があります。Grok はそのディレクトリ内のすべての `hooks/*.json` ファイルを統合するため、インストールは Herdr の `SessionStart` エントリだけを含む `hooks/herdr.json` と `hooks/herdr-agent-state.sh`（Windows では `hooks/herdr-agent-state.ps1`）を書き込み、ほかのフックファイルには触れません。アンインストールは Herdr 所有のこの 2 ファイルだけを削除します。
|
||||
|
||||
Grok がセッション開始イベントを発行した後、Herdr は報告されたセッション id を使って `grok --resume <id>` でペインを resume できます。
|
||||
|
||||
|
||||
@@ -9,10 +9,11 @@ Herdr プラグインマーケットプレイスは、コミュニティ製プ
|
||||
|
||||
## プラグインを探す
|
||||
|
||||
[マーケットプレイス](/plugins/)には、GitHub トピック `herdr-plugin` が付いた
|
||||
すべての公開リポジトリが掲載されます。名前、オーナー、説明、言語で検索でき、
|
||||
人気順、最近の活動順、新着順で並べ替えられます。各掲載はソースリポジトリの
|
||||
GitHub ページに直接リンクしています。
|
||||
[マーケットプレイス](/plugins/)には、GitHub トピック `herdr-plugin` が付いており、
|
||||
デフォルトブランチに必須メタデータを解析できる `herdr-plugin.toml` が 1 つ以上ある
|
||||
公開リポジトリが掲載されます。リポジトリとプラグインのメタデータを検索でき、
|
||||
リポジトリカードを人気順、最近の活動順、新着順で並べ替えられます。各カードは
|
||||
ソースリポジトリにリンクし、その中で検出されたすべてのプラグインを表示します。
|
||||
|
||||
掲載は自動かつ無審査です。掲載されているのはリポジトリが自らトピックを
|
||||
付けたからであって、Herdr が検証したからではありません。インストールする前に
|
||||
@@ -35,19 +36,17 @@ herdr plugin install owner/repo[/subdir...]
|
||||
|
||||
## 自分のプラグインを掲載する
|
||||
|
||||
公開リポジトリに GitHub トピック `herdr-plugin` を追加してください。
|
||||
インデックスが使うシグナルはこのトピックだけなので、公開プラグインに
|
||||
トピックを付けるだけで掲載されます。インデックスは 30 分ごとに自動更新される
|
||||
ため、新しくトピックを付けたリポジトリはまもなく表示され、トピックを外した
|
||||
リポジトリは次回の更新で消えます。
|
||||
公開リポジトリに GitHub トピック `herdr-plugin` を追加し、デフォルトブランチに
|
||||
必須メタデータを解析できる `herdr-plugin.toml` を 1 つ以上置いてください。
|
||||
マニフェストはルートにもサブディレクトリにも配置できます。マーケットプレイスは
|
||||
1 リポジトリにつき 1 枚のカードを使い、有効な各マニフェストを個別にインストール
|
||||
できるプラグインとして表示します。インデックスは 30 分ごとに自動更新されます。
|
||||
|
||||
## 掲載に表示される内容
|
||||
|
||||
各カードには GitHub リポジトリのメタデータが表示されます: リポジトリ名と
|
||||
オーナー、説明、スター数、主要言語、最終 push 時刻、そしてソースへのリンクです。
|
||||
インデックスは GitHub のリポジトリ検索からこれらを読み取るため、リポジトリの
|
||||
説明とトピックを正確に保つことが、掲載を有用にする鍵になります。
|
||||
|
||||
インデックスはまだ `herdr-plugin.toml` を解析しないため、プラグインの `id`、
|
||||
宣言された `platforms`、`min_herdr_version` といったマニフェストのフィールドは
|
||||
v1 では表示されません。フォークとアーカイブ済みリポジトリは一覧から除外されます。
|
||||
各カードには GitHub リポジトリの名前、オーナー、説明、スター数、主要言語、
|
||||
最終 push 時刻が表示されます。プラグイン行には各マニフェストの `name` と `version`
|
||||
が表示され、正確なソースディレクトリにリンクします。インデックスにはパス、`id`、
|
||||
`name`、`version`、`platforms`、`min_herdr_version` と、デフォルトブランチの正確な
|
||||
コミットが記録されます。フォーク、アーカイブ済みリポジトリ、有効なプラグイン
|
||||
マニフェストがないリポジトリ、不正なメタデータは一覧から除外されます。
|
||||
|
||||
@@ -63,11 +63,9 @@ Host workbox
|
||||
herdr --remote workbox
|
||||
```
|
||||
|
||||
リモートアタッチは x86_64 と aarch64 の Linux および macOS ホストをサポートします。Herdr はリモートのプラットフォームを確認し、リモートの `PATH` 上にある一致する `herdr` を優先し、次に `~/.local/bin/herdr` を確認します。一致するバイナリがない場合、対話的な実行では `~/.local/bin/herdr` へのインストールを提案します。非対話的な実行はホストを変更せずに失敗します。`~/.local/bin` がリモートの `PATH` にない場合、Herdr はインストール後に警告します。
|
||||
リモートアタッチは、Linux、macOS、Windows のローカルクライアントから、x86_64 と aarch64 の Linux および macOS ホストへの接続をサポートします。Herdr はリモートのプラットフォームを確認し、リモートの `PATH` 上にある一致する `herdr` を優先してから、一般的な直接インストール、Homebrew、mise、Nix プロファイルのパスを確認します。一致するバイナリがない場合、対話的な実行では `~/.local/bin/herdr` へのインストールを提案します。非対話的な実行はホストを変更せずに失敗します。`~/.local/bin` がリモートの `PATH` にない場合、Herdr はインストール後に警告します。Windows をリモートホストとして使うことはできません。
|
||||
|
||||
ネイティブ Windows の `herdr --remote` は Windows ベータの範囲外です。Windows からはサーバーに SSH してそこで `herdr` を実行してください。
|
||||
|
||||
デフォルトでは、`herdr --remote` はあなたの SSH config を最初に include し、その後にフォールバックのキープアライブ設定を加えた一時的な SSH config を通してブリッジを実行します。既存のユーザーのキープアライブ設定が優先されます。Herdr が生成するブリッジ設定を使わず素の `ssh` を使うには `[remote].manage_ssh_config = false` を設定してください。
|
||||
デフォルトでは、`herdr --remote` はユーザーの SSH config を最初に include し、その後にフォールバックのキープアライブ設定を加えた一時的な SSH config を通してリモートセットアップとブリッジを実行します。既存のユーザーのキープアライブ設定が優先されます。Linux と macOS クライアントは接続再利用用のプライベートなアタッチ単位コントロールソケットも使いますが、Windows OpenSSH では使いません。Herdr が生成する設定やコントロールソケットを使わず通常の `ssh` を使うには `[remote].manage_ssh_config = false` を設定してください。
|
||||
|
||||
デフォルトでは、実行中のリモートサーバーの置き換えや再起動が必要な場合、リモートアタッチは通常の再起動/停止フローを使います。対応する実行中リモートサーバーで実験的なライブハンドオフにオプトインするには `--handoff` を渡します:
|
||||
|
||||
|
||||
@@ -358,10 +358,13 @@ v1 には Herdr が管理するプラグインストレージ API はありま
|
||||
## マーケットプレイス
|
||||
|
||||
コミュニティ製プラグインは[マーケットプレイス](/plugins/)で探せます。これは
|
||||
GitHub トピック `herdr-plugin` が付いた公開 GitHub リポジトリの自動インデックスです。
|
||||
プラグインは普通の GitHub リポジトリのままです: `herdr-plugin.toml` を含めて公開し、
|
||||
GitHub トピック `herdr-plugin` が付いており、必須メタデータを解析できる
|
||||
`herdr-plugin.toml` が 1 つ以上ある公開 GitHub リポジトリの自動インデックスです。
|
||||
プラグインは普通の GitHub リポジトリのままです: 公開して
|
||||
`herdr plugin install owner/repo[/subdir]` を共有してください。
|
||||
|
||||
プラグインを掲載するには、公開リポジトリに GitHub トピック `herdr-plugin` を
|
||||
追加します。インデックスは 30 分ごとに更新されます。発見の仕組みは
|
||||
プラグインを掲載するには、公開リポジトリに GitHub トピック `herdr-plugin` を追加し、
|
||||
デフォルトブランチのルートまたはサブディレクトリにマニフェストを置きます。
|
||||
1 つのリポジトリカードに複数のプラグインを掲載できます。インデックスは 30 分ごとに
|
||||
更新されます。発見の仕組みは
|
||||
[マーケットプレイス](/ja/docs/marketplace/)を参照してください。
|
||||
|
||||
@@ -76,6 +76,7 @@ Herdr が resume するのは、現行の公式 Herdr インテグレーショ
|
||||
| Droid | `2` | `droid --resume <id>` |
|
||||
| Kimi Code CLI | `3` | `kimi --session <id>` |
|
||||
| Qoder CLI | `2` | `qodercli --resume <id>` |
|
||||
| Qwen Code | `1` | `qwen --resume <id>` |
|
||||
| OpenCode | `5` | `opencode --session <id>` |
|
||||
| Kilo Code CLI | `1` | `kilo --session <id>` |
|
||||
| Hermes Agent | `2` | `hermes --resume <id>` |
|
||||
|
||||
@@ -107,7 +107,7 @@ herdr pane read w1:p2 --source recent --lines 50
|
||||
| インテグレーション | `integration.install`、`integration.uninstall` |
|
||||
| プラグイン | `plugin.link`、`plugin.list`、`plugin.unlink`、`plugin.enable`、`plugin.disable`、`plugin.action.list`、`plugin.action.invoke`、`plugin.log.list`、`plugin.pane.open`、`plugin.pane.focus`、`plugin.pane.close` |
|
||||
|
||||
`agent.wait` はサーバー所有でイベント駆動です。解決したペイン占有者に固定されるため、置換されたエージェントが待機を満たすことはありません。`agent.prompt` は `until` と `timeout_ms` を持つ省略可能な `wait` オブジェクトを受け付けます。これにより、プロンプト送信と待機開始を 1 つのリクエストで行い、別々の呼び出し間の競合を避けられます。
|
||||
`agent.wait` はサーバー所有でイベント駆動です。解決したペイン占有者に固定されるため、置換されたエージェントが待機を満たすことはありません。`agent.prompt` は `until` と `timeout_ms` を持つ省略可能な `wait` オブジェクトを受け付けます。これにより、プロンプト送信と待機開始を 1 つのリクエストで行い、別々の呼び出し間の競合を避けられます。解決したエージェントがすでに `blocked` の場合、`agent.prompt` は入力を送信せず、待機も開始せずに `agent_blocked` を返します。
|
||||
|
||||
`workspace.move_block` は、順序付きの `workspace_ids` を `before_workspace_id` の前へアトミックに移動します。アンカーを省略するとブロックを末尾へ移動します。id は一意である必要があり、アンカーをブロックに含めることはできません。レスポンスにはサーバーが確定した順序付きワークスペース一覧が含まれます。
|
||||
|
||||
@@ -273,7 +273,7 @@ reason の候補は `shown`、`disabled`、`rate_limited`、`no_foreground_clien
|
||||
{"id":"req_title_clear","method":"client.window_title.clear","params":{}}
|
||||
```
|
||||
|
||||
`client.window_title.clear` は Herdr のデフォルトタイトルを復元します。レスポンスは `type: "client_window_title"` で、`changed` と、`set`、`cleared`、`no_foreground_client` のいずれかの reason を含みます。
|
||||
`client.window_title.clear` はタイトルを `ui.window_title` に戻します。レスポンスは `type: "client_window_title"` で、`changed` と、`set`、`cleared`、`no_foreground_client` のいずれかの reason を含みます。
|
||||
|
||||
Worktree メソッドは Git チェックアウトを Herdr ワークスペースとして管理します。`worktree.create` はチェックアウトを作成し、新しい `workspace`、`tab`、`root_pane`、`worktree` のレコードを返します。要求されたブランチがローカルに既存ならそれをチェックアウトし、なければ要求されたベースまたは `HEAD` からブランチを作成します。`worktree.open` は既存のチェックアウトを開くか、すでに開いているワークスペースを返します。`worktree.remove` はリンクされた子ワークスペースに対して `git worktree remove` を実行し、ブランチは決して削除しません。
|
||||
|
||||
|
||||
@@ -26,6 +26,8 @@ Windows ベータビルドはプレビューチャンネルでのみ提供され
|
||||
| ローカル永続セッション | ベータ |
|
||||
| ConPTY によるネイティブペイン | ベータ |
|
||||
| Windows Terminal / PowerShell アプリからのアタッチ | ベータ |
|
||||
| Linux/macOS ホストへの `herdr --remote` | ベータ |
|
||||
| リモートクリップボード画像と画像ファイルのドロップ | ベータ |
|
||||
| `cmd.exe` ペイン | ベータ |
|
||||
| 起動時 cwd とワークスペースラベル | ベータ |
|
||||
| ペイン起動時の cwd | ベータ |
|
||||
@@ -47,14 +49,14 @@ Windows のエージェントプロセス検出は、ペインのシェルの子
|
||||
| --- | --- |
|
||||
| シェルで `cd` した後のライブ cwd | 部分的 |
|
||||
| シェルインテグレーション/OSC7 によるライブ cwd | ベータ |
|
||||
| エージェントへのクリップボード画像貼り付け | 未検証 |
|
||||
| ローカルペインのエージェントへのクリップボード画像貼り付け | 未検証 |
|
||||
| CJK IME の変換候補位置 | 部分的 |
|
||||
| Kitty graphics のレンダリング | 未検証 |
|
||||
| ホストカーソル描画 | 部分的 |
|
||||
|
||||
Herdr はペインを正しいディレクトリで起動でき、Herdr を起動したディレクトリから最初のワークスペースを作成できます。起動後の PowerShell のディレクトリ変更は別問題です: Herdr が調べられるプロセスのフィールドは、その後の論理的な `cd` の変化を確実には追跡しません。ライブ cwd の報告には Herdr インテグレーションかプロンプトのシェルインテグレーションを使ってください。
|
||||
|
||||
Windows Terminal は特定のエージェント向けに画像貼り付け経路をサポートしているかもしれませんが、Herdr 自身のクリップボード画像リーダーはまだ Windows に配線されていません。Windows のクリップボードブリッジが実装・テストされるまで、`alt+v` の画像貼り付けは未検証として扱ってください。リモートクリップボードの画像ブリッジは別機能で、引き続き Unix/macOS の `herdr --remote` に紐づいています。
|
||||
`herdr --remote` では、設定されたリモート画像貼り付けキーが Windows のクリップボード画像を読み取り、リモートホストへ転送します。Windows Terminal にローカル画像ファイルをひとつドロップした場合も、そのファイルを転送してリモート側のパスを貼り付けます。ローカルのネイティブ Windows ペインへのクリップボード画像貼り付けは、引き続き未検証です。
|
||||
|
||||
Kitty graphics は実験的なままで、まだ Windows でのサポートを謳っていません。Windows Terminal での画像レンダリングを特にテストしているのでない限り、`experimental.kitty_graphics = false` のままにしてください。
|
||||
|
||||
@@ -92,22 +94,20 @@ Herdr のペインテキストコピーは Windows ベータで動作します
|
||||
| 機能 | 状況 |
|
||||
| --- | --- |
|
||||
| ダイレクトターミナルアタッチ | 未サポート |
|
||||
| Windows バイナリからの `herdr --remote` | 未サポート |
|
||||
| `herdr --remote` の接続先としての Windows | 未サポート |
|
||||
| ライブサーバーハンドオフ | 未サポート |
|
||||
| Unix ファイルディスクリプタのハンドオフ | 未サポート |
|
||||
| Unix フォアグラウンドプロセスグループ | 未サポート |
|
||||
| リモートクリップボード画像ブリッジ | 未サポート |
|
||||
| プレフィックスによる入力ソース切り替え | 未サポート |
|
||||
| 署名済みバイナリ / SmartScreen 回避 | 未サポート |
|
||||
|
||||
Windows からのリモート作業は、サーバーに SSH してそこで `herdr` を実行してください:
|
||||
Windows Terminal からは、Linux や macOS と同じリモートコマンドを使います:
|
||||
|
||||
```powershell
|
||||
ssh you@server
|
||||
herdr
|
||||
herdr --remote workbox
|
||||
```
|
||||
|
||||
このモードでは Herdr はリモートホスト上で動きます。ネイティブ Windows の `herdr --remote` はベータの範囲外です。
|
||||
接続先ホストは Linux または macOS である必要があります。Herdr はインストール済みの Windows OpenSSH クライアントと SSH 設定を使います。Windows OpenSSH では Herdr の Unix コントロールソケットによる接続再利用を使わないため、セットアップ中の繰り返しプロンプトを避けるには Windows の `ssh-agent` による鍵認証を推奨します。
|
||||
|
||||
Windows のアップデートは Windows インストーラー経由で行われ、バージョン付きインストールジャンクションを更新します。アップデート後は実行中の Herdr セッションを再起動してください。ライブハンドオフは Unix 専用です。
|
||||
|
||||
|
||||
@@ -7,13 +7,13 @@ description: What the prefix is, which bindings to learn first, and how to go pr
|
||||
You already know this model. Jump to the [keybinding reference](/docs/configuration/#keybindings) for the full default keymap and config syntax.
|
||||
:::
|
||||
|
||||
Herdr is mouse-native. You can click panes, tabs, workspaces, and agents, drag split borders, and use right-click menus without learning a single keybinding. Keyboard control is an optional layer, not a requirement.
|
||||
Herdr is mouse-native. You can click panes, tabs, workspaces, and agents, drag split borders, and use right-click menus without learning a single keybinding. Keyboard control is optional.
|
||||
|
||||
## What the prefix is
|
||||
|
||||
A terminal multiplexer sits between your terminal and the programs running inside it. Those programs already use most key combinations: `ctrl+c` interrupts, `ctrl+r` searches history, editors claim nearly everything else. If Herdr grabbed common keys directly, it would break the programs inside it.
|
||||
|
||||
The prefix solves this. Press the prefix key, default `ctrl+b`, and the next keypress goes to Herdr instead of your terminal. `prefix+c` means: press `ctrl+b`, release, then press `c`. One reserved key instead of dozens.
|
||||
The prefix solves this. Press the prefix key, default `ctrl+b`, and the next keypress goes to Herdr instead of your terminal. `prefix+c` means: press `ctrl+b`, release, then press `c`. Herdr reserves one key instead of dozens.
|
||||
|
||||
Press `prefix+?` at any time to see every active binding. Press `/` in the keybind help to filter actions and shortcuts; use Backspace to edit the filter or `ctrl+u` to clear it.
|
||||
|
||||
@@ -64,7 +64,7 @@ The full keymap and the binding syntax live in the [keybinding reference](/docs/
|
||||
|
||||
## Copy mode
|
||||
|
||||
Press `prefix+[` to enter copy mode for the focused pane. Use `h/j/k/l`, tmux-style `w/b/e`, `{`/`}`, `PageUp`/`PageDown`, `ctrl+b`/`ctrl+f`, and `ctrl+u`/`ctrl+d` to move. Press `/` or `?` for forward or backward literal search, then `n` or `N` to repeat in the same or opposite direction. Search is case-insensitive unless the query contains an uppercase letter. Use `v` or Space to start a selection, `y` or Enter to copy it, and `q` or Esc to leave without copying. Esc clears an active selection or search before exiting. Copy mode does not pause the pane process: output remains live, follows at the bottom, and stays pinned when you navigate into history. The configured prefix keeps its normal meaning in copy mode; with the default prefix, `ctrl+b` enters prefix mode instead of paging up, so use a different prefix if you want `ctrl+b` for copy-mode page-up. Mouse drag-select copies without entering copy mode at all.
|
||||
Press `prefix+[` to enter copy mode for the focused pane. Use `h/j/k/l`, tmux-style `w/b/e` and big-word `W/B/E`, `{`/`}`, `PageUp`/`PageDown`, `ctrl+b`/`ctrl+f`, and `ctrl+u`/`ctrl+d` to move. Press `/` or `?` for forward or backward literal search, then `n` or `N` to repeat in the same or opposite direction. Search is case-insensitive unless the query contains an uppercase letter. Use `v` or Space to start a selection, `y` or Enter to copy it, and `q` or Esc to leave without copying. Esc clears an active selection or search before exiting. Copy mode does not pause the pane process: output remains live, follows at the bottom, and stays pinned when you navigate into history. The configured prefix keeps its normal meaning in copy mode; with the default prefix, `ctrl+b` enters prefix mode instead of paging up, so use a different prefix if you want `ctrl+b` for copy-mode page-up. Mouse drag-select copies without entering copy mode at all.
|
||||
|
||||
## Change anything
|
||||
|
||||
@@ -81,7 +81,7 @@ You can bind Herdr actions to direct chords that need no prefix at all. The hard
|
||||
|
||||
Any chord works as a binding: `ctrl+j`, `alt+k`, whatever fits your hands. But a chord has to survive three layers before Herdr sees it: your operating system, your outer terminal (Ghostty, iTerm2, and others ship their own defaults), and the programs running inside the pane. `ctrl+j` reaches Herdr fine, but shells and editors treat it as enter. `alt+k` is free on Linux, but macOS composes it into a special character in most terminals. If you pick chords from these families, double-check them against your own terminal and OS shortcuts.
|
||||
|
||||
We mapped the default keybindings of Ghostty, iTerm2, Terminal.app, kitty, WezTerm, Alacritty, Warp, Windows Terminal, GNOME Terminal, and Konsole, plus the global shortcuts of GNOME and KDE. One modifier family is almost untouched everywhere: `ctrl+alt`. Terminals leave it free, it is not affected by the macOS option-key composing behavior that blocks plain `alt` chords, and it transmits even in terminals without a modern keyboard protocol. It is the safe default recommendation; the choice stays yours.
|
||||
We mapped the default keybindings of Ghostty, iTerm2, Terminal.app, kitty, WezTerm, Alacritty, Warp, Windows Terminal, GNOME Terminal, and Konsole, plus the global shortcuts of GNOME and KDE. One modifier family is almost untouched everywhere: `ctrl+alt`. Terminals leave it free, it is not affected by the macOS option-key composing behavior that blocks plain `alt` chords, and it transmits even in terminals without a modern keyboard protocol. It is a safe default, but the choice is yours.
|
||||
|
||||
This setup keeps the prefix bindings working and adds direct chords on top:
|
||||
|
||||
|
||||
@@ -3,16 +3,18 @@ title: Marketplace
|
||||
description: Discover community Herdr plugins on GitHub, and get your own plugin listed.
|
||||
---
|
||||
|
||||
The Herdr plugin marketplace is a discoverable index of community plugins.
|
||||
Browse it at [herdr.dev/plugins](/plugins/). It is an automatic index of public
|
||||
GitHub repositories, not a reviewed catalog.
|
||||
The Herdr plugin marketplace indexes community plugins. Browse it at
|
||||
[herdr.dev/plugins](/plugins/). The index covers public GitHub repositories; it
|
||||
is not a reviewed catalog.
|
||||
|
||||
## Browse plugins
|
||||
|
||||
The [marketplace](/plugins/) lists every public repository tagged with the
|
||||
GitHub topic `herdr-plugin`. Search by name, owner, description, or language,
|
||||
and sort by popularity, recent activity, or newest. Each listing links straight
|
||||
to its source repository on GitHub.
|
||||
The [marketplace](/plugins/) lists public repositories tagged with the GitHub
|
||||
topic `herdr-plugin` when their default branch contains at least one
|
||||
`herdr-plugin.toml` whose required metadata can be parsed. Search by repository
|
||||
or plugin metadata, and sort repository cards by popularity, recent activity,
|
||||
or newest. Each card links to its source repository and lists every discovered
|
||||
plugin inside it.
|
||||
|
||||
Discovery is automatic and unreviewed. A listing means a repository tagged
|
||||
itself, not that Herdr vetted it, so the
|
||||
@@ -21,33 +23,32 @@ anything.
|
||||
|
||||
## Install a plugin
|
||||
|
||||
The marketplace adds discovery on top of installation; it does not replace it.
|
||||
Install any plugin straight from GitHub:
|
||||
The marketplace helps you discover plugins. Install any plugin straight from
|
||||
GitHub:
|
||||
|
||||
```bash
|
||||
herdr plugin install owner/repo[/subdir...]
|
||||
```
|
||||
|
||||
Publish a normal public GitHub repository with a `herdr-plugin.toml` manifest at
|
||||
its root, or in a subdirectory, and that command works. See
|
||||
The command works with a public GitHub repository that has a
|
||||
`herdr-plugin.toml` manifest at its root or in a subdirectory. See
|
||||
[Plugins](/docs/plugins/) for the manifest and authoring reference.
|
||||
|
||||
## Get your plugin listed
|
||||
|
||||
Add the GitHub topic `herdr-plugin` to a public repository. That topic is the
|
||||
only signal the index uses, so tagging a public plugin is all it takes. The
|
||||
index refreshes automatically every 30 minutes, so a newly tagged repository
|
||||
shows up shortly after, and one that drops the topic disappears on the next
|
||||
refresh.
|
||||
Add the GitHub topic `herdr-plugin` to a public repository and put one or more
|
||||
`herdr-plugin.toml` manifests with parseable required metadata on its default
|
||||
branch. Manifests may be at the root or in subdirectories. The marketplace uses
|
||||
one card per repository and lists each valid manifest as a separately
|
||||
installable plugin. The index refreshes automatically every 30 minutes and
|
||||
rescans repositories when their default-branch head changes.
|
||||
|
||||
## What a listing shows
|
||||
|
||||
Each card shows GitHub repository metadata: the repository name and owner, its
|
||||
description, star count, primary language, and the time it was last pushed, with
|
||||
a link back to the source. The index reads this from GitHub's repository search,
|
||||
so keeping your repository description and topics accurate is what makes your
|
||||
listing useful.
|
||||
|
||||
The index does not parse `herdr-plugin.toml` yet, so manifest fields like the
|
||||
plugin `id`, declared `platforms`, and `min_herdr_version` are not shown in v1.
|
||||
Forks and archived repositories are excluded from the list.
|
||||
description, star count, primary language, and the time it was last pushed. Its
|
||||
plugin rows show each manifest's `name` and `version` and link to the exact
|
||||
source directory. The index records the manifest path, `id`, `name`, `version`,
|
||||
`platforms`, and `min_herdr_version` together with the exact default-branch
|
||||
commit. Forks, archived repositories, repositories without a valid plugin
|
||||
manifest, and malformed manifest metadata are excluded.
|
||||
|
||||
@@ -37,14 +37,14 @@ herdr session delete side-project --json
|
||||
|
||||
## Remote attach over SSH
|
||||
|
||||
There are two remote modes; [How to work with Herdr](/docs/how-to-work/) compares them. SSH to the server and run `herdr` there for the tmux-style path. Or attach through SSH from your local machine:
|
||||
Herdr supports two remote modes. [How to work with Herdr](/docs/how-to-work/) compares them. SSH to the server and run `herdr` there for the tmux-style path, or attach through SSH from your local machine:
|
||||
|
||||
```bash
|
||||
herdr --remote workbox
|
||||
herdr --remote ssh://you@server:2222
|
||||
```
|
||||
|
||||
In this mode your local Herdr is a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.
|
||||
In this mode, your local Herdr is a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.
|
||||
|
||||
By default, `herdr --remote` uses your local Herdr keybindings for that attach. This keeps local muscle memory even when the remote server has different config. The local keybindings are a snapshot from attach time; detach and reattach after editing local keybindings. Use `--remote-keybindings server` when you want the remote server config instead. Local custom command keybindings are not sent, because those commands would run on the remote host.
|
||||
|
||||
@@ -63,11 +63,9 @@ Then attach with:
|
||||
herdr --remote workbox
|
||||
```
|
||||
|
||||
Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks common direct, Homebrew, mise, and Nix profile install paths. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.
|
||||
Remote attach supports Linux, macOS, and Windows local clients connecting to Linux or macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks common direct, Homebrew, mise, and Nix profile install paths. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install. Windows is not supported as the remote host.
|
||||
|
||||
Native Windows `herdr --remote` is not part of the Windows beta. From Windows, SSH into the server and run `herdr` there.
|
||||
|
||||
By default, `herdr --remote` runs remote setup and the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings and a private per-attach control socket for connection reuse. Existing user keepalive settings win. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated config or control socket.
|
||||
By default, `herdr --remote` runs remote setup and the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings. Existing user keepalive settings win. Linux and macOS clients also use a private per-attach control socket for connection reuse; Windows OpenSSH does not. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated config or control socket.
|
||||
|
||||
Remote attach uses your normal OpenSSH authentication. If the target uses a passphrase-protected key in a non-interactive shell, script, CI job, or mobile terminal that cannot show the passphrase prompt, load the key into ssh-agent first:
|
||||
|
||||
@@ -84,7 +82,7 @@ By default, remote attach uses the normal restart/stop flow if it needs to repla
|
||||
herdr --remote workbox --handoff
|
||||
```
|
||||
|
||||
If you SSH into the server first and run `herdr` there, Herdr runs entirely on the server. That mode is useful and simple, but it cannot access your local desktop clipboard beyond normal terminal text paste.
|
||||
If you SSH into the server first and run `herdr` there, Herdr runs entirely on the server and cannot access your local desktop clipboard beyond normal terminal text paste.
|
||||
|
||||
When your local and remote platforms match, Herdr can copy the current local binary for direct installs. For Homebrew, mise, and Nix installs, or when the platforms differ, it downloads the matching release asset for the current client version from `https://herdr.dev/latest.json`.
|
||||
|
||||
@@ -162,4 +160,4 @@ Use `--no-session` to run Herdr without the background server/client split:
|
||||
herdr --no-session
|
||||
```
|
||||
|
||||
This is mainly an escape hatch for debugging or compatibility. The default persistent session mode is the normal path.
|
||||
Use `--no-session` mainly for debugging or compatibility. Persistent session mode remains the default.
|
||||
|
||||
@@ -15,19 +15,18 @@ workspaces, panes, agents, and a stable CLI/socket API. Plugins turn that
|
||||
existing extension surface into reusable workflows that people can build,
|
||||
install, and share without adding every workflow to Herdr itself.
|
||||
|
||||
A plugin is not an SDK integration. It is a directory with a
|
||||
`herdr-plugin.toml` manifest and commands Herdr can launch. Herdr validates the
|
||||
manifest, injects runtime context, starts the declared commands, and records
|
||||
logs. The commands call back into Herdr through the CLI or socket when they need
|
||||
to do more work.
|
||||
A plugin is a directory with a `herdr-plugin.toml` manifest and commands Herdr
|
||||
can launch. Herdr validates the manifest, injects runtime context, starts the
|
||||
declared commands, and records logs. The commands call back into Herdr through
|
||||
the CLI or socket when they need to do more work.
|
||||
|
||||
There is no separate plugin SDK or restricted command set. The entire Herdr CLI
|
||||
is the plugin API: every command in the [CLI reference](/docs/cli-reference/) is
|
||||
available to a plugin, and anything you can run as `herdr ...` yourself a plugin
|
||||
can run too. Most plugins should call Herdr through `HERDR_BIN_PATH`, which
|
||||
points at the running Herdr binary. That keeps plugins portable across Unix
|
||||
sockets and Windows named pipes. Use the [socket API](/docs/socket-api/) when
|
||||
you want to send raw JSON requests yourself.
|
||||
is the plugin API. Every command in the
|
||||
[CLI reference](/docs/cli-reference/) is available to a plugin, and a plugin can
|
||||
run anything you can run yourself as `herdr ...`. Most plugins should call Herdr
|
||||
through `HERDR_BIN_PATH`, which points at the running Herdr binary. That keeps
|
||||
plugins portable across Unix sockets and Windows named pipes. Use the
|
||||
[socket API](/docs/socket-api/) when you want to send raw JSON requests yourself.
|
||||
|
||||
Runtime action registration and native non-terminal plugin UI are not part of
|
||||
plugin v1. Actions, event hooks, panes, and link handlers are all declared in
|
||||
@@ -35,22 +34,22 @@ the manifest.
|
||||
|
||||
## Trust and security
|
||||
|
||||
A plugin is ordinary code that runs on your machine. When you install or link
|
||||
one, its build and runtime commands run as your user, with your environment, and
|
||||
can call the full Herdr CLI — the same as any extension you add to an editor,
|
||||
shell, or coding agent. That openness is the point, and a little judgment keeps
|
||||
it safe.
|
||||
A plugin is ordinary code that runs on your machine. Its build and runtime
|
||||
commands run as your user, inherit your environment, and can call the full Herdr
|
||||
CLI. Treat a plugin like any extension you add to an editor, shell, or coding
|
||||
agent.
|
||||
|
||||
Install plugins from authors and repositories you trust, and skim what a new one
|
||||
does first: the `herdr-plugin.toml` manifest and the scripts or binaries it runs.
|
||||
`herdr plugin install` shows a preview of the source and the commands it will run
|
||||
in interactive terminals, so you can review before confirming. Use `--yes` for
|
||||
Install or link plugins only from authors and repositories you trust. Before
|
||||
installing or linking one, skim the `herdr-plugin.toml` manifest and the scripts
|
||||
or binaries it runs. `herdr plugin install` shows a preview of the source and
|
||||
the commands it will run in interactive terminals, so you can review before
|
||||
confirming. Use `--yes` for
|
||||
sources you already trust, and pin `--ref` when you want a specific revision.
|
||||
|
||||
Herdr validates the manifest and keeps each plugin's config and state in its own
|
||||
directory, but it does not review or sandbox what a plugin does. Third-party
|
||||
plugins come from their authors, not from Herdr, so they are yours to vet and run
|
||||
at your own discretion.
|
||||
directory, but it does not review or sandbox plugin code. Third-party plugins
|
||||
come from their authors, not Herdr; you are responsible for deciding whether to
|
||||
run them.
|
||||
|
||||
## Manifest
|
||||
|
||||
@@ -213,8 +212,8 @@ reinstall from GitHub to refresh a managed plugin.
|
||||
|
||||
The example cookbook repo is `ogulcancelik/herdr-plugin-examples`. It contains
|
||||
separate example plugins in subdirectories, including `agent-telegram-notify`,
|
||||
`github-link-preview`, and `dev-layout-bootstrap`. These are examples to copy,
|
||||
not maintained official plugins.
|
||||
`github-link-preview`, and `dev-layout-bootstrap`. Use them as examples to copy;
|
||||
Herdr does not maintain them as official plugins.
|
||||
|
||||
## Build commands
|
||||
|
||||
@@ -240,9 +239,9 @@ is linked or enabled. Herdr starts them asynchronously and records their
|
||||
completion in the normal plugin command log. A startup failure does not stop the
|
||||
server.
|
||||
|
||||
Startup hooks are one-shot initialization commands, not supervised daemons. A
|
||||
hook should restore plugin-owned state, call any required Herdr APIs, and exit.
|
||||
For example, a plugin can save a declarative Agent view under
|
||||
Startup hooks are one-shot initialization commands rather than supervised
|
||||
daemons. A hook should restore plugin-owned state, call any required Herdr APIs,
|
||||
and exit. For example, a plugin can save a declarative Agent view under
|
||||
`HERDR_PLUGIN_STATE_DIR`, then read and reapply that view from its startup hook.
|
||||
|
||||
Startup hooks receive the normal runtime plugin environment and
|
||||
@@ -363,10 +362,13 @@ state should own their files or database.
|
||||
## Marketplace
|
||||
|
||||
Community plugins are discoverable in the [marketplace](/plugins/), an automatic
|
||||
index of public GitHub repositories tagged with the topic `herdr-plugin`.
|
||||
Plugins stay ordinary GitHub repositories: publish one with `herdr-plugin.toml`,
|
||||
then share `herdr plugin install owner/repo[/subdir]`.
|
||||
index of public GitHub repositories tagged with `herdr-plugin` that contain one
|
||||
or more `herdr-plugin.toml` files whose required metadata can be parsed. Plugins
|
||||
stay ordinary GitHub repositories: publish one, then share
|
||||
`herdr plugin install owner/repo[/subdir]`.
|
||||
|
||||
To get a plugin listed, add the GitHub topic `herdr-plugin` to its public
|
||||
repository. The index refreshes every 30 minutes. See
|
||||
To get plugins listed, add the GitHub topic `herdr-plugin` and place their
|
||||
manifests at the root or in subdirectories of the repository's default branch.
|
||||
One repository card can contain multiple separately installable plugins. The
|
||||
index refreshes every 30 minutes. See
|
||||
[Marketplace](/docs/marketplace/) for how discovery works.
|
||||
|
||||
@@ -13,15 +13,15 @@ Herdr launches or attaches to your default background session. You do not manage
|
||||
|
||||
## Create a workspace
|
||||
|
||||
When a session has no workspaces, Herdr opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace; this keeps agent state readable in the sidebar.
|
||||
When a session has no workspaces, Herdr opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace to keep agent state readable in the sidebar.
|
||||
|
||||
## Use the mouse
|
||||
|
||||
Herdr is mouse-native, so start by clicking. Click panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard; double-click a token to copy it directly. Copying does not require Ctrl+C.
|
||||
Herdr is mouse-native, so start by clicking panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard; double-click a token to copy it directly. Copying does not require Ctrl+C.
|
||||
|
||||
Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and visible `http://` or `https://` URLs. On macOS, use Ctrl-click for Herdr-handled pane links while mouse capture is enabled; Cmd-click is only available through the terminal-native bypass path, such as Shift-Cmd-click or `ui.mouse_capture = false`.
|
||||
|
||||
If you configure `ui.right_click_passthrough_modifier`, that modifier plus right-click sends right-click, hold, and drag gestures to mouse-reporting pane apps.
|
||||
If you configure `ui.right_click_passthrough_modifier`, that modifier plus right-click sends right-click, hold, and drag gestures to mouse-reporting pane apps. To make normal right-click go to one pane app, choose **Send right-clicks to pane** from that pane's menu or run `herdr pane input --current --right-click pane` inside it. Right-click the pane frame to reopen Herdr's menu.
|
||||
|
||||
## Run an agent
|
||||
|
||||
@@ -31,7 +31,7 @@ Start your coding agent in a pane:
|
||||
claude
|
||||
```
|
||||
|
||||
Or `codex`, `pi`, `opencode`, or any other [supported agent](/docs/agents/). Herdr detects it automatically. The sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle` — across every workspace, so you always know which project needs you.
|
||||
Or `codex`, `pi`, `opencode`, or any other [supported agent](/docs/agents/). Herdr detects it automatically. Across every workspace, the sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle`, so you always know which project needs you.
|
||||
|
||||
## Keyboard control
|
||||
|
||||
@@ -49,13 +49,13 @@ Common actions:
|
||||
| New workspace | `prefix+shift+n` |
|
||||
| Detach client | `prefix+q` |
|
||||
|
||||
New to the prefix idea? [Keyboard](/docs/keyboard/) explains what it is, why multiplexers use one, and how to go prefix-free. Press `prefix+?` inside Herdr to see every active binding, and `prefix+[` to copy from the keyboard in copy mode.
|
||||
If the prefix idea is new to you, [Keyboard](/docs/keyboard/) explains what it is, why multiplexers use one, and how to go prefix-free. Press `prefix+?` inside Herdr to see every active binding, and `prefix+[` to copy from the keyboard in copy mode.
|
||||
|
||||
## Detach and come back
|
||||
|
||||
Press `prefix+q` or simply close your terminal window. The Herdr server and every agent keep running. Run `herdr` again to reattach to the same session.
|
||||
|
||||
To actually end the session and stop its panes:
|
||||
To end the session and stop its panes:
|
||||
|
||||
```bash
|
||||
herdr server stop
|
||||
|
||||
@@ -3,7 +3,7 @@ title: Session state and restore
|
||||
description: Understand what Herdr keeps live, restores after restart, replays from history, resumes through agent integrations, and hands off during updates.
|
||||
---
|
||||
|
||||
Herdr has several state paths. They solve different problems.
|
||||
Herdr uses several state paths for different situations.
|
||||
|
||||
## What survives
|
||||
|
||||
@@ -14,8 +14,6 @@ Herdr has several state paths. They solve different problems.
|
||||
| Update without `--handoff` | Compatible servers keep running; restart-required servers may need stop/restart | Yes after restart | Only with pane screen history | Only with native agent session restore |
|
||||
| Update with `--handoff` | Best effort for supported running servers | Yes | Yes, from the live terminal if handoff succeeds | Yes, because the process keeps running if handoff succeeds |
|
||||
|
||||
The sections below explain each path.
|
||||
|
||||
## Live persistence
|
||||
|
||||
Normal detach keeps the Herdr server running. Panes, shells, agents, servers, tests, and command processes keep running inside that server.
|
||||
@@ -36,9 +34,9 @@ Snapshot restore does not preserve running shells, servers, tests, or arbitrary
|
||||
|
||||
## Pane screen history replay
|
||||
|
||||
Pane screen history restores recent terminal contents after a full server restart. It restores what Herdr can show, not the old process.
|
||||
Pane screen history restores recent terminal contents after a full server restart without restoring the old process.
|
||||
|
||||
This is off by default because pane output can include secrets, tokens, prompts, and command output. Enable it in the config file:
|
||||
Pane screen history is off by default because pane output can include secrets, tokens, prompts, and command output. Enable it in the config file:
|
||||
|
||||
```toml
|
||||
[experimental]
|
||||
@@ -51,7 +49,7 @@ When enabled, Herdr stores saved pane history in `session-history.json` next to
|
||||
|
||||
Some agents can resume their own conversation sessions. Herdr can use official integration-reported session references to restart supported agent panes after a Herdr server restart.
|
||||
|
||||
This is enabled by default. Disable it with:
|
||||
Native agent session restore is enabled by default. Disable it with:
|
||||
|
||||
```toml
|
||||
[session]
|
||||
@@ -78,6 +76,7 @@ Native session restore requires these Herdr integration versions or newer:
|
||||
| Droid | `2` | `droid --resume <id>` |
|
||||
| Kimi Code CLI | `3` | `kimi --session <id>` |
|
||||
| Qoder CLI | `2` | `qodercli --resume <id>` |
|
||||
| Qwen Code | `1` | `qwen --resume <id>` |
|
||||
| OpenCode | `5` | `opencode --session <id>` |
|
||||
| Kilo Code CLI | `1` | `kilo --session <id>` |
|
||||
| Hermes Agent | `2` | `hermes --resume <id>` |
|
||||
@@ -93,9 +92,9 @@ If native agent session restore applies to a pane, Herdr resumes the agent sessi
|
||||
|
||||
Live handoff is for update and remote attach flows that need to replace a running Herdr server. It asks the old server to transfer live panes to the new server, so pane processes can keep running across the server replacement.
|
||||
|
||||
This is different from snapshot restore, pane history replay, and native agent session restore. Handoff tries to keep the current processes alive. The others reconstruct state after the old server has already stopped.
|
||||
Unlike snapshot restore, pane history replay, and native agent session restore, handoff tries to keep the current processes alive rather than reconstructing state after the old server stops.
|
||||
|
||||
Handoff protects long-lived server-owned session state: pane PTYs and processes, agent identity and durable metadata, and plugin/session state needed by the replacement server. It does not preserve transient coordination across the replacement boundary. In-flight CLI or API requests, waits, subscription streams, client sockets, and pane-to-pane messages may be interrupted; clients should reconnect and retry them.
|
||||
A successful handoff preserves long-lived server-owned session state: pane PTYs and processes, agent identity and durable metadata, and plugin/session state needed by the replacement server. It does not preserve transient coordination across the replacement boundary. In-flight CLI or API requests, waits, subscription streams, client sockets, and pane-to-pane messages may be interrupted; clients should reconnect and retry them.
|
||||
|
||||
Live handoff is experimental and opt-in:
|
||||
|
||||
|
||||
@@ -111,7 +111,7 @@ Raw socket method names use dot notation:
|
||||
| Integrations | `integration.install`, `integration.uninstall` |
|
||||
| Plugins | `plugin.link`, `plugin.list`, `plugin.unlink`, `plugin.enable`, `plugin.disable`, `plugin.action.list`, `plugin.action.invoke`, `plugin.log.list`, `plugin.pane.open`, `plugin.pane.focus`, `plugin.pane.close` |
|
||||
|
||||
`agent.wait` is server-owned and event-driven. It pins the resolved pane occupant so a replacement cannot satisfy the wait. `agent.prompt` accepts an optional `wait` object with `until` and `timeout_ms`; this submits the prompt and starts the wait in one request, avoiding a race between separate calls.
|
||||
`agent.wait` is server-owned and event-driven. It pins the resolved pane occupant so a replacement cannot satisfy the wait. `agent.prompt` accepts an optional `wait` object with `until` and `timeout_ms`; this submits the prompt and starts the wait in one request, avoiding a race between separate calls. If the resolved agent is already `blocked`, `agent.prompt` returns `agent_blocked` without sending input or starting the wait.
|
||||
|
||||
`workspace.move_block` atomically moves the ordered `workspace_ids` before `before_workspace_id`; omit the anchor to move the block to the end. The ids must be unique and the anchor cannot be part of the block. The response contains the authoritative ordered workspace list.
|
||||
|
||||
@@ -145,7 +145,8 @@ like `ctrl+h`, `control+j`, `alt+x`, and `shift+tab`, function keys like
|
||||
{"id":"req_focus","method":"pane.focus_direction","params":{"direction":"right"}}
|
||||
{"id":"req_resize","method":"pane.resize","params":{"pane_id":"w1:p1","direction":"right","amount":0.1}}
|
||||
{"id":"req_zoom","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"toggle"}}
|
||||
{"id":"req_split","method":"pane.split","params":{"direction":"right","ratio":0.333,"env":{"HERDR_ROLE":"tests"}}}
|
||||
{"id":"req_input","method":"pane.input.set","params":{"pane_id":"w1:p1","right_click":"pane"}}
|
||||
{"id":"req_split","method":"pane.split","params":{"direction":"right","ratio":0.333,"right_click":"pane","env":{"HERDR_ROLE":"tests"}}}
|
||||
{"id":"req_process","method":"pane.process_info","params":{"pane_id":"w1:p1"}}
|
||||
```
|
||||
|
||||
@@ -153,6 +154,13 @@ like `ctrl+h`, `control+j`, `alt+x`, and `shift+tab`, function keys like
|
||||
Herdr returns that pane. When it is omitted, Herdr returns the active focused
|
||||
pane.
|
||||
|
||||
`pane.input.set` sets `right_click` to `herdr` or `pane` for one pane. `herdr`
|
||||
is the default. `pane` forwards unmodified right-click hold and drag gestures
|
||||
when the application requests terminal mouse reporting; otherwise Herdr falls
|
||||
back to its pane menu. Right-clicking the pane frame always opens Herdr's menu.
|
||||
`pane.split` accepts the same optional `right_click` value for the newly created
|
||||
pane.
|
||||
|
||||
`PaneInfo` includes `scroll` when terminal scroll metrics are available:
|
||||
|
||||
```json
|
||||
@@ -169,10 +177,20 @@ Clients can treat `offset_from_bottom == 0` as at-bottom state.
|
||||
|
||||
Pane graphics let a plugin place image data over a pane. They are available
|
||||
only when `[experimental].kitty_graphics = true`; otherwise every pane graphics
|
||||
method returns `feature_disabled`. Calling `pane.graphics.info` returns the
|
||||
attached client's cell width and height in pixels without creating a graphics
|
||||
layer. `pane.graphics.set` accepts `png`, `rgb`, or `rgba` data in `data_base64`,
|
||||
and `pane.graphics.clear` removes the layer.
|
||||
method returns `feature_disabled`. Calling `pane.graphics.info` explicitly
|
||||
activates capability discovery and returns the attached client's cell size,
|
||||
file-frame options, pixel-mouse support, the 16-layer limit, and `pane_visible`.
|
||||
`pane_visible` is true only when the target is in the active workspace and tab
|
||||
and is not hidden by zoom. Short-lived UI modes do not change it.
|
||||
|
||||
`pane.graphics.set`, `pane.graphics.clear`, and `pane.graphics.stream` accept an
|
||||
optional `layer_id` (default `primary`). Set and stream also accept `z_index`;
|
||||
layers are placed in stable `(z_index, layer_id)` order. Each stream exclusively owns its layer, and
|
||||
closing it removes that layer. Inline frames accept `png`, `rgb`, `rgba`, or
|
||||
`bgra`; BGRA is normalized once to owned RGBA. Herdr advances the host cache
|
||||
one image transaction per render pass, so arbitrary layer sets progress without
|
||||
an aggregate frame. Headless transport keeps each transaction within its 32 MiB
|
||||
wire limit; local monolithic rendering does not apply that transport limit.
|
||||
|
||||
```json
|
||||
{"id":"graphics_info","method":"pane.graphics.info","params":{"pane_id":"w1:p1"}}
|
||||
@@ -182,14 +200,38 @@ and `pane.graphics.clear` removes the layer.
|
||||
|
||||
For repeated frames, open a dedicated socket with `pane.graphics.stream`. After
|
||||
Herdr replies with `ok`, send one JSON header and then exactly `data_length` raw
|
||||
bytes per frame. A stream owns that pane's graphics layer until the socket
|
||||
closes; concurrent set, clear, or stream requests return `stream_conflict`.
|
||||
bytes per inline frame. Concurrent operations on that layer return
|
||||
`stream_conflict`.
|
||||
|
||||
```json
|
||||
{"id":"graphics_stream","method":"pane.graphics.stream","params":{"pane_id":"w1:p1"}}
|
||||
{"id":"graphics_stream","method":"pane.graphics.stream","params":{"pane_id":"w1:p1","z_index":0}}
|
||||
{"format":"png","image_width":800,"image_height":600,"data_length":12345,"placement":{"viewport_col":0,"viewport_row":0,"grid_cols":80,"grid_rows":30}}
|
||||
```
|
||||
|
||||
When `pane.graphics.info` advertises `file_frame_transport: "direct-kitty"`, an
|
||||
eligible local Ghostty, kitty, or WezTerm client may submit an immutable private
|
||||
`rgba` or `bgra` file with `file.path`, `sequence`, and `revision`. Direct Kitty
|
||||
file transport is reserved for the default `primary` page layer; named secondary
|
||||
layers use owned inline RGBA. BGRA is always copied, swizzled, and rendered
|
||||
inline. Herdr replies with a `pane_graphics_frame_ack` only after the terminal
|
||||
accepts the file, or after a safe owned inline fallback is installed. Confirmed
|
||||
file-transport failure disables direct files for that client connection without
|
||||
disabling exact pixel mouse. A timeout or client loss closes the stream without
|
||||
acknowledging source reuse. Monolithic `--no-session` mode advertises neither
|
||||
fast file transport nor exact pixel mouse and remains on owned inline fallback.
|
||||
|
||||
Direct files are always complete canonical `width * height * 4` RGBA frames.
|
||||
`file_frame_max_bytes` is the limit that remains eligible for owned inline fallback.
|
||||
Primary-layer RGBA files may use the larger `file_frame_direct_max_bytes` limit when
|
||||
`file_frame_transport` is available. Frames above the fallback limit are acknowledged
|
||||
only when the terminal accepts the direct transfer; rejection closes the stream. If a
|
||||
frame cannot use owned inline fallback while its pane is temporarily hidden or cannot be
|
||||
placed during a redraw, Herdr uploads the image without displaying it and replays its
|
||||
placement when the pane becomes visible again.
|
||||
`file_frame_damage: true` means Herdr accepts optional damage metadata for
|
||||
producer-side canonical-ring efficiency; it still copies or presents the full file.
|
||||
Resize and full redraw replay placements without retransmitting pixels.
|
||||
|
||||
`pane.layout` returns the tab layout snapshot with `workspace_id`, `tab_id`,
|
||||
`zoomed`, outer `area`, `focused_pane_id`, pane rects, and split rects/ratios.
|
||||
`pane.neighbor` and `pane.edges` include that same layout snapshot so clients
|
||||
@@ -340,7 +382,7 @@ Set or clear the foreground client's outer terminal window title:
|
||||
{"id":"req_title_clear","method":"client.window_title.clear","params":{}}
|
||||
```
|
||||
|
||||
`client.window_title.clear` restores Herdr's default title. The response is
|
||||
`client.window_title.clear` hands the title back to `ui.window_title`. The response is
|
||||
`type: "client_window_title"` with `changed` and reason `set`, `cleared`, or
|
||||
`no_foreground_client`.
|
||||
|
||||
@@ -445,10 +487,10 @@ A source mismatch leaves the active view unchanged. Set and clear responses use
|
||||
|
||||
## Plugin APIs
|
||||
|
||||
The plugin API is an early host surface for executable workflow tools. A plugin
|
||||
is a package with a `herdr-plugin.toml` manifest. The manifest declares
|
||||
startup hooks, shareable actions, event hooks, terminal pane entrypoints, and
|
||||
link handlers. Startup hooks run once after restore when the API is ready.
|
||||
The plugin API is an early interface for executable workflow tools. A plugin is
|
||||
a package with a `herdr-plugin.toml` manifest. The manifest declares startup
|
||||
hooks, shareable actions, event hooks, terminal pane entrypoints, and link
|
||||
handlers. Startup hooks run once after restore when the API is ready.
|
||||
Actions and panes are manifest-only; runtime action registration and runtime
|
||||
argv pane creation are not part of v1.
|
||||
|
||||
@@ -457,11 +499,14 @@ Installed and linked plugins persist across restarts. Herdr writes a
|
||||
`plugin.unlink`, `plugin.enable`, and `plugin.disable`. The
|
||||
`herdr plugin install` and `herdr plugin link` CLIs also write the same registry
|
||||
when Herdr is not running, then startup loads it automatically. On startup,
|
||||
Herdr re-reads each
|
||||
manifest from its original path; if the file is missing or unparseable the entry
|
||||
is kept with a `warnings` field so `plugin.list` surfaces it.
|
||||
Herdr re-reads each manifest from its original path; if the file is missing or
|
||||
unparseable, the entry is kept with a `warnings` field so `plugin.list` surfaces
|
||||
it.
|
||||
|
||||
Event hook `on` values are validated against the known Herdr event names at link time. An unrecognised name is not an error — the link still succeeds — but the returned plugin info includes a warning (e.g. `"unknown event 'worktree.craeted'"`). Check the `warnings` field in the `plugin.link` and `plugin.list` responses.
|
||||
Herdr validates event hook `on` values against known event names at link time.
|
||||
An unrecognised name does not block the link, but the returned plugin info
|
||||
includes a warning (e.g. `"unknown event 'worktree.craeted'"`). Check the
|
||||
`warnings` field in the `plugin.link` and `plugin.list` responses.
|
||||
|
||||
Link a local plugin manifest:
|
||||
|
||||
@@ -517,7 +562,7 @@ field is missing, invalid, or newer than the running Herdr binary.
|
||||
|
||||
Declare `platforms` at the top level with the OS identifiers (`linux`, `macos`,
|
||||
`windows`) your plugin supports. Omitting `platforms` is allowed for local
|
||||
development — `plugin.link` succeeds but the response includes a warning.
|
||||
development. `plugin.link` succeeds, but the response includes a warning.
|
||||
Individual build commands, actions, event hooks, panes, and link handlers can
|
||||
declare their own `platforms` to override the plugin-level list; if omitted they
|
||||
inherit from the plugin. Invoking an action or opening a pane whose effective
|
||||
@@ -660,7 +705,8 @@ Integrations report agent state with `pane.report_agent`.
|
||||
}
|
||||
```
|
||||
|
||||
`state` is semantic. It affects waits, notifications, and rollups. Report display-only values separately through metadata.
|
||||
`state` carries semantic agent state and affects waits, notifications, and
|
||||
rollups. Report display-only values separately through metadata.
|
||||
|
||||
Session-only official integrations report native session references with `pane.report_agent_session`. State-reporting integrations can still include native session references in `pane.report_agent`. State-independent session reports do not affect waits, notifications, or rollups.
|
||||
|
||||
@@ -882,6 +928,7 @@ Errors look like this:
|
||||
|
||||
## Protocol stability
|
||||
|
||||
Herdr has a protocol version for client/server compatibility. Protocol changes are reviewed with release compatibility in mind.
|
||||
Herdr has a protocol version for client/server compatibility. Protocol changes
|
||||
are reviewed for release compatibility.
|
||||
|
||||
Check the server protocol with `ping` or `herdr status` before depending on new behavior. Handle unknown fields gracefully.
|
||||
|
||||
@@ -27,9 +27,9 @@ Native mode restores the IME anchor but may reintroduce occasional cursor moveme
|
||||
|
||||
## Enter, Tab, or Backspace fires twice
|
||||
|
||||
Older terminal versions can emit the release of Enter, Tab, and Backspace as the same bytes as the press when an application enables Kitty keyboard event reporting. Herdr cannot distinguish those duplicate bytes after the terminal sends them.
|
||||
Older versions of some terminals can emit the release of Enter, Tab, and Backspace as the same bytes as the press when an application enables Kitty keyboard event reporting. Herdr cannot distinguish those duplicate bytes after the terminal sends them.
|
||||
|
||||
Update the outer terminal to a version containing its upstream fix:
|
||||
Update the outer terminal to a version that contains its upstream fix:
|
||||
|
||||
| Terminal | Minimum fixed version |
|
||||
| --- | --- |
|
||||
@@ -72,7 +72,7 @@ Stopping a server exits its pane processes. Named sessions use `herdr session st
|
||||
|
||||
## The `herdr` command is not found
|
||||
|
||||
Restart the terminal so it reloads its environment, then confirm the Herdr install directory is on `PATH`. Package-manager installs must be updated and exposed through that package manager. See [Install Herdr](/docs/install/#verify).
|
||||
Restart the terminal so it reloads its environment, then confirm the Herdr install directory is on `PATH`. For package-manager installs, use that package manager to update Herdr and expose it on `PATH`. See [Install Herdr](/docs/install/#verify).
|
||||
|
||||
## A direct keybinding does nothing
|
||||
|
||||
|
||||
@@ -3,11 +3,11 @@ title: Windows beta
|
||||
description: Native Windows support status, supported workflows, and known limitations.
|
||||
---
|
||||
|
||||
Native Windows support is experimental beta.
|
||||
Native Windows support is an 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.
|
||||
Herdr on Windows uses ConPTY and Windows process/runtime behavior instead of the Unix PTY model Herdr was built around, so feature support varies. 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.
|
||||
The beta gathers feedback from real use: install success, pane reliability, agent workflows, bug volume, missing features, and whether Windows users get 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:
|
||||
|
||||
@@ -26,6 +26,8 @@ For internal beta testing, `HERDR_MANIFEST_URL` can point the installer at a cus
|
||||
| Local persistent sessions | beta |
|
||||
| Native panes through ConPTY | beta |
|
||||
| Windows Terminal / PowerShell app attach | beta |
|
||||
| `herdr --remote` to Linux/macOS hosts | beta |
|
||||
| Remote clipboard images and image-file drops | beta |
|
||||
| `cmd.exe` panes | beta |
|
||||
| Startup cwd and workspace labels | beta |
|
||||
| Pane launch cwd | beta |
|
||||
@@ -39,7 +41,7 @@ For internal beta testing, `HERDR_MANIFEST_URL` can point the installer at a cus
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
@@ -47,14 +49,14 @@ Plugins support `windows` as a manifest platform in preview. GitHub install, loc
|
||||
| --- | --- |
|
||||
| Live cwd after shell `cd` | partial |
|
||||
| Live cwd via shell integration/OSC7 | beta |
|
||||
| Clipboard image paste to agents | unverified |
|
||||
| Clipboard image paste to agents in local panes | 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.
|
||||
Herdr can launch panes in the right directory and create the initial workspace from the directory where you started Herdr. After startup, the process field Herdr can inspect does not reliably track later logical `cd` changes in PowerShell. 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`.
|
||||
During `herdr --remote`, the configured remote image paste key reads a Windows clipboard image and transfers it to the remote host. Dropping one local image file into Windows Terminal also transfers that file and pastes its remote path. Clipboard image paste into a local native Windows pane remains unverified.
|
||||
|
||||
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.
|
||||
|
||||
@@ -62,18 +64,18 @@ Kitty graphics remains experimental and is not claimed as Windows-supported yet.
|
||||
|
||||
### 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.
|
||||
Herdr relies on ConPTY for native Windows panes. The Windows terminal cursor path can expose intermediate 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:
|
||||
Windows does not use a drawn cursor 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.
|
||||
Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output.
|
||||
|
||||
### Keyboard and mouse
|
||||
|
||||
@@ -92,22 +94,20 @@ For text paste, use `ctrl+shift+v` in Windows Terminal. Multiline text paste is
|
||||
| Capability | Status |
|
||||
| --- | --- |
|
||||
| Direct terminal attach | unsupported |
|
||||
| `herdr --remote` from the Windows binary | unsupported |
|
||||
| Windows as a `herdr --remote` target host | 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:
|
||||
From Windows Terminal, use the same remote command as Linux and macOS:
|
||||
|
||||
```powershell
|
||||
ssh you@server
|
||||
herdr
|
||||
herdr --remote workbox
|
||||
```
|
||||
|
||||
That mode runs Herdr on the remote host. Native Windows `herdr --remote` is not part of the beta.
|
||||
The target host must run Linux or macOS. Herdr uses the installed Windows OpenSSH client and your SSH configuration. Windows OpenSSH does not use Herdr's Unix control-socket reuse, so key authentication through Windows `ssh-agent` is recommended to avoid repeated prompts during remote setup.
|
||||
|
||||
Windows updates run through the Windows installer and update the versioned install junction. Restart running Herdr sessions after updating. Live handoff is Unix-only.
|
||||
|
||||
|
||||
@@ -41,9 +41,9 @@ review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
||||
|
||||
可用的 shell 窗格必须停在交互式 shell 提示符,由 shell 自身占用前台,没有正在前台运行的命令、编辑器或智能体。调用 `agent start` 前先让窗格回到提示符。
|
||||
|
||||
`--kind` 选择受支持的智能体及其标准可执行文件。支持的 kind 是 `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli` 和 `maki`。`--` 后的参数会原样传给该可执行文件。
|
||||
`--kind` 选择受支持的智能体及其标准可执行文件。支持的 kind 是 `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`qwen` 和 `maki`。`--` 后的参数会原样传给该可执行文件。
|
||||
|
||||
`agent start` 只有在 Herdr 于同一终端检测到预期智能体,并确认它可接受交互输入后才返回。默认等待启动 30 秒;`--timeout` 必须大于 3000 且不超过 300000 毫秒。
|
||||
成功的 `agent start` 只有在 Herdr 于同一终端检测到预期智能体,并确认它可接受交互输入后才返回。如果启动期间检测到 `blocked`,命令会立即返回 `agent_not_ready`。该名称仍可用于 `agent read` 和 `agent send-keys`,检测变为 `idle` 后即可用于发送提示。默认等待启动 30 秒;`--timeout` 必须大于 3000 且不超过 300000 毫秒。
|
||||
|
||||
```bash
|
||||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
@@ -69,11 +69,11 @@ herdr agent rename w1:p2 reviewer
|
||||
| 向智能体交互界面发送按键 | `agent send-keys` |
|
||||
| 等待智能体生命周期状态 | `agent wait` |
|
||||
|
||||
`agent prompt` 会提交文本和编码后的 Enter,并遵循终端当前的 bracketed paste 模式。即使智能体正在 working 也可以提交。使用 `agent send-keys` 进行 `esc`、`up`、`enter`、`ctrl+c` 等交互;`escape` 也是 `esc` 的别名。只有在明确需要原始终端控制时才使用窗格输入命令。
|
||||
`agent prompt` 会先发送文本,短暂延迟后再发送编码后的 Enter,并遵循终端当前的 bracketed paste 模式。即使智能体正在 working 也可以提交。如果智能体已经是 `blocked`,它不会发送任何终端输入,而是返回 `agent_blocked`;请先检查对话框,再用 `agent send-keys` 明确作出响应。使用 `agent send-keys` 进行 `esc`、`up`、`enter`、`ctrl+c` 等交互;`escape` 也是 `esc` 的别名。只有在明确需要原始终端控制时才使用窗格输入命令。
|
||||
|
||||
窗格输入直接指定终端,不关心当前进程。智能体输入会解析实时智能体;如果该智能体已不再控制此窗格,操作会被拒绝。
|
||||
|
||||
`agent prompt --wait` 会立即提交提示。智能体从非 working 状态开始时，Herdr 首先要求在五秒内观察到生命周期变化。如果状态序列没有前进，它会返回 `agent_prompt_stalled`，而不是无限等待；调用方设置的 `--timeout` 不超过五秒时，仍返回普通的 `timeout` 错误。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。独立的 `agent wait` 会观察当前智能体；如果状态已经匹配，就会立即返回。两者默认匹配 `idle`、`done` 或 `blocked`。可以重复使用 `--until` 接受多个精确状态，例如 `--until idle --until done`；需要 `unknown` 时请明确使用 `--until unknown`。在 `agent prompt` 中，`--until` 必须与 `--wait` 一起使用。
|
||||
除非智能体已经是 `blocked`,`agent prompt --wait` 会立即提交提示。已经是 `blocked` 时,它不会开始等待,而是返回 `agent_blocked`。已接受的提示从其他非 working 状态开始时,Herdr 首先要求在五秒内观察到生命周期变化。如果状态序列没有前进，它会返回 `agent_prompt_stalled`，而不是无限等待；调用方设置的 `--timeout` 不超过五秒时，仍返回普通的 `timeout` 错误。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。独立的 `agent wait` 会观察当前智能体；如果状态已经匹配，就会立即返回。两者默认匹配 `idle`、`done` 或 `blocked`。可以重复使用 `--until` 接受多个精确状态，例如 `--until idle --until done`；需要 `unknown` 时请明确使用 `--until unknown`。在 `agent prompt` 中，`--until` 必须与 `--wait` 一起使用。
|
||||
|
||||
`idle` 表示智能体正等待输入,且其标签页已在聚焦的 Herdr 界面中显示。`done` 是相同的底层 idle 状态,但用于后台工作完成后,直到该标签页获得焦点或 `pane focus` / `agent focus` 指向它。仅通过 CLI 读取不会把它标记为已查看。`blocked` 表示 Herdr 识别到了审批或提问界面。`unknown` 表示智能体存在,但 Herdr 无法可靠判断其生命周期;它不代表工作成功完成。区别重要时,请指定精确的 `--until` 状态。
|
||||
|
||||
|
||||
@@ -20,6 +20,7 @@ Herdr 为同时运行多个编程智能体而生。每个智能体都待在一
|
||||
| Kimi Code CLI | 安装后为生命周期钩子;否则为屏幕清单 | 状态与会话 |
|
||||
| Hermes Agent | 屏幕清单 | 会话 |
|
||||
| Qoder CLI | 屏幕清单 | 会话 |
|
||||
| Qwen Code | 屏幕清单 | 会话 |
|
||||
| Droid | 屏幕清单 | 会话 |
|
||||
| OpenCode | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 |
|
||||
| Kilo Code CLI | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 |
|
||||
@@ -103,7 +104,7 @@ herdr integration install claude
|
||||
herdr integration status
|
||||
```
|
||||
|
||||
每个受支持的智能体都有自己的集成名称和行为。按智能体的细节和完整安装列表见[集成](/zh-cn/docs/integrations/)。
|
||||
每个受支持的智能体都有自己的集成名称和行为。按智能体的细节和完整安装列表见[集成](/zh-cn/docs/integrations/)。如果你正在构建智能体,[自定义集成指南](/zh-cn/docs/integrations/#集成你自己的智能体)介绍了如何在不为 Herdr 添加原生支持的情况下上报生命周期状态。
|
||||
|
||||
## 自定义智能体标签
|
||||
|
||||
|
||||
@@ -285,11 +285,11 @@ herdr agent explain --file PATH --agent LABEL [--json|--verbose]
|
||||
|
||||
智能体目标只能是唯一的实时智能体名称,或当前承载该智能体的窗格 ID。终端 ID 和单独的智能体 kind 标签不能作为目标。通过 `agent start` 启动的智能体必须有名称;手动启动的智能体保持未命名,通过窗格 ID 寻址。
|
||||
|
||||
`agent start` 会在现有可用 shell 窗格中启动智能体:交互式 shell 必须占用前台,不能有正在前台运行的命令、编辑器或智能体。拓扑必须单独创建。名称在实时智能体中必须唯一,并匹配 `[a-z][a-z0-9_-]{0,31}`。支持的 kind 是 `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli` 和 `maki`。名称属于当前窗格占用者,在该智能体退出、release 或被替换时清除;短暂的检测不确定不会清除它。
|
||||
`agent start` 会在现有可用 shell 窗格中启动智能体:交互式 shell 必须占用前台,不能有正在前台运行的命令、编辑器或智能体。拓扑必须单独创建。名称在实时智能体中必须唯一,并匹配 `[a-z][a-z0-9_-]{0,31}`。支持的 kind 是 `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli`、`qwen` 和 `maki`。名称属于当前窗格占用者,在该智能体退出、release 或被替换时清除;短暂的检测不确定不会清除它。
|
||||
|
||||
start 只有在预期智能体占用同一终端并可接受交互输入后才返回。默认启动超时是 30000 毫秒;显式值必须大于 3000 且不超过 300000。
|
||||
成功的 start 只有在预期智能体占用同一终端并可接受交互输入后才返回。如果启动期间检测到 `blocked`,命令会立即返回 `agent_not_ready`。该名称仍可用于 `agent read` 和 `agent send-keys`,检测变为 `idle` 后即可用于发送提示。默认启动超时是 30000 毫秒;显式值必须大于 3000 且不超过 300000。
|
||||
|
||||
`agent prompt` 遵循当前的 bracketed paste 模式，即使智能体处于 working 也会原子地提交文本和编码后的 Enter。使用 `--wait` 时，从非 working 状态发送的提示必须在五秒内产生可观察的生命周期变化，否则 Herdr 返回 `agent_prompt_stalled`；调用方超时不超过五秒时，仍返回普通的 `timeout` 错误。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。`--until` 用于缩小匹配状态，不带 `--wait` 时会被拒绝。独立的 `agent wait` 在当前状态匹配时立即返回。两者默认匹配 `idle`、`done` 或 `blocked`；需要 `unknown` 时请明确使用 `--until unknown`。
|
||||
`agent prompt` 遵循当前的 bracketed paste 模式,即使智能体处于 working 也会先发送文本,短暂延迟后再发送编码后的 Enter。如果智能体已经是 `blocked`,它不会发送输入,而是返回 `agent_blocked`。使用 `--wait` 时,从其他非 working 状态接受的提示必须在五秒内产生可观察的生命周期变化，否则 Herdr 返回 `agent_prompt_stalled`；调用方超时不超过五秒时，仍返回普通的 `timeout` 错误。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。`--until` 用于缩小匹配状态，不带 `--wait` 时会被拒绝。独立的 `agent wait` 在当前状态匹配时立即返回。两者默认匹配 `idle`、`done` 或 `blocked`；需要 `unknown` 时请明确使用 `--until unknown`。
|
||||
|
||||
`idle` 表示智能体在等待输入,且其标签页已在聚焦的 Herdr 界面中显示。`done` 是相同的底层 idle 状态,用于未查看的后台工作完成后。聚焦该标签页或用 `pane focus` / `agent focus` 指向它会标记为已查看;仅通过 CLI 读取不会改变它。`blocked` 表示 Herdr 识别到审批或提问界面。`unknown` 表示智能体存在但无法可靠分类,不代表工作成功。
|
||||
|
||||
@@ -308,7 +308,7 @@ herdr terminal title clear
|
||||
```
|
||||
|
||||
从直接附加中用 `ctrl+b q` 分离。用 `ctrl+b ctrl+b` 发送字面的 `ctrl+b`。
|
||||
`terminal title clear` 恢复 Herdr 默认的外层终端窗口标题。
|
||||
`terminal title clear` 把外层终端窗口标题交还给 `ui.window_title`。
|
||||
|
||||
## 输出等待
|
||||
|
||||
@@ -340,6 +340,7 @@ herdr integration install kilo
|
||||
herdr integration install hermes
|
||||
herdr integration install mastracode
|
||||
herdr integration install qodercli
|
||||
herdr integration install qwen
|
||||
herdr integration install cursor
|
||||
herdr integration uninstall pi
|
||||
herdr integration uninstall omp
|
||||
@@ -354,6 +355,7 @@ herdr integration uninstall kilo
|
||||
herdr integration uninstall hermes
|
||||
herdr integration uninstall mastracode
|
||||
herdr integration uninstall qodercli
|
||||
herdr integration uninstall qwen
|
||||
herdr integration uninstall cursor
|
||||
herdr integration status [--outdated-only]
|
||||
```
|
||||
|
||||
@@ -50,6 +50,18 @@ herdr server reload-config
|
||||
|
||||
重载会在不重启窗格的情况下应用大多数 UI 设置。仅启动时生效的设置仍需重启。
|
||||
|
||||
## 无客户端终端尺寸
|
||||
|
||||
没有客户端连接时，服务器会使用 120×40 的虚拟终端进行布局并创建新窗格。可通过以下配置更改用于无客户端编排的回退尺寸：
|
||||
|
||||
```toml
|
||||
[server]
|
||||
headless_cols = 160
|
||||
headless_rows = 50
|
||||
```
|
||||
|
||||
客户端连接后，其尺寸仍决定共享运行时的大小。客户端断开后，现有窗格 PTY 会保留上次连接时的尺寸，而新的无客户端布局会使用配置的回退值。
|
||||
|
||||
## 终端默认值
|
||||
|
||||
设置 Herdr 创建新交互式窗格时使用的可执行文件：
|
||||
@@ -98,14 +110,14 @@ Git 工作区行提供 worktree 操作。`New worktree` 会创建检出：如果
|
||||
|
||||
## 远程连接
|
||||
|
||||
远程连接默认使用临时保活设置和连接复用兜底来管理 SSH 连接。
|
||||
远程连接默认使用临时保活设置，并在支持时复用连接，以管理 SSH 连接。
|
||||
|
||||
```toml
|
||||
[remote]
|
||||
manage_ssh_config = true
|
||||
```
|
||||
|
||||
启用后，`herdr --remote` 会写入一份私有的临时 SSH 配置：先包含你的 `~/.ssh/config` 和 `/etc/ssh/ssh_config`，再添加兜底的 `ServerAliveInterval` 和 `ServerAliveCountMax` 值。你自己的保活设置优先。Herdr 还会为每次远程连接使用私有的 OpenSSH control socket，以复用首次通过身份验证的连接。设置 `manage_ssh_config = false` 可通过普通 `ssh` 进行远程连接，不使用 Herdr 生成的配置或 control socket。
|
||||
启用后，`herdr --remote` 会写入一份私有的临时 SSH 配置：先包含用户和系统 SSH 配置，再添加兜底的 `ServerAliveInterval` 和 `ServerAliveCountMax` 值。你自己的保活设置优先。Linux 和 macOS 客户端还会为每次远程连接使用私有的 OpenSSH control socket，以复用首次通过身份验证的连接；Windows OpenSSH 不使用此复用方式。设置 `manage_ssh_config = false` 可通过普通 `ssh` 进行远程连接，不使用 Herdr 生成的配置或 control socket。
|
||||
|
||||
## 按键绑定
|
||||
|
||||
@@ -137,7 +149,15 @@ split_horizontal = "prefix+minus"
|
||||
next_tab = ["prefix+n", "ctrl+alt+]"]
|
||||
```
|
||||
|
||||
可选动作默认不设置。使用 `prefix+` 可获得前缀模式行为；当你确实需要直接快捷键时，请使用显式的修饰组合键。
|
||||
可选动作默认不设置。使用 `prefix+` 可获得前缀模式行为；当你确实需要直接快捷键时，请使用显式的修饰组合键。例如，可以像 tmux 一样通过一次按键调整窗格大小，而无需进入调整大小模式：
|
||||
|
||||
```toml
|
||||
[keys]
|
||||
resize_pane_left = "ctrl+shift+alt+left"
|
||||
resize_pane_down = "ctrl+shift+alt+down"
|
||||
resize_pane_up = "ctrl+shift+alt+up"
|
||||
resize_pane_right = "ctrl+shift+alt+right"
|
||||
```
|
||||
|
||||
按键字符串支持普通按键、`ctrl+a`、`shift+n`、`alt+1`、`cmd+k` 等修饰组合键，以及 `enter`、`tab`、`esc`、`left`、`right`、`up`、`down` 等特殊键。也支持 `minus`、`comma`、`ampersand`、`plus`、`backtick` 等命名标点。直接绑定 `n` 这样的普通可打印键并不安全，因为它会拦截输入；除非你有意设置直接绑定，否则请使用 `prefix+n`。`navigate_workspace_*` 和 `navigate_pane_*` 字段仅在导航模式中生效，可以使用 `j` 或 `k` 等普通按键；它们不得使用 `prefix+`、`esc`、`enter`、`tab`、`shift+tab`、`left`、`right`，也不得使用无修饰键的 `1` 到 `9`。左右方向键是向左和向右导航窗格的永久别名。这些导航模式快捷键独立于 `focus_pane_down = "prefix+j"` 等通用动作绑定；两者使用同一按键时，打开导航模式后，导航模式快捷键优先。Alt、Cmd/Super 以及带修饰键的标点取决于你的终端和 tmux 设置。
|
||||
|
||||
@@ -238,6 +258,9 @@ dark_name = "catppuccin"
|
||||
|
||||
```toml
|
||||
[theme.custom]
|
||||
sidebar_bg = "#181825"
|
||||
active_row_bg = "#1e1e2e"
|
||||
selection_bg = "#313244"
|
||||
panel_bg = "reset"
|
||||
accent = "#a6e3a1"
|
||||
green = "#a6e3a1"
|
||||
@@ -246,12 +269,60 @@ red = "#f38ba8"
|
||||
yellow = "#f9e2af"
|
||||
```
|
||||
|
||||
`sidebar_bg` 可单独设置桌面侧边栏的背景色。省略时，侧边栏继续使用宿主终端背景。`active_row_bg` 可更改当前 Space 和已聚焦 Agent 行的背景色，而不会影响分隔线或滚动条轨道。`selection_bg` 可更改侧边栏中 Navigate 模式光标行的背景色。
|
||||
|
||||
颜色值支持十六进制、命名颜色、`rgb(r,g,b)`，以及 `reset`、`default`、`none`、`transparent` 等重置别名。
|
||||
|
||||
## UI 与侧边栏
|
||||
|
||||
侧边栏是 Herdr 的主仪表盘。在[配置参考](/docs/config-reference/)中搜索 `ui.`，可查看尺寸、折叠模式、Agent 面板排序、鼠标行为、窗格边框和其他显示设置。
|
||||
|
||||
在 `[ui]` 下设置 `tab_bar_position = "bottom"`，可将桌面标签栏放到终端窗格下方。Prefix、Navigate、Copy 和 Resize 模式栏会在显示期间临时替换底部标签栏。默认值为 `"top"`。
|
||||
|
||||
可在标签栏右侧配置一个类似 tmux 的有序状态区：
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
tab_bar_right = [
|
||||
{ type = "zoom" },
|
||||
{ type = "hostname" },
|
||||
{ type = "datetime", format = "%H:%M" },
|
||||
{ type = "text", text = "prod" },
|
||||
{ type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
|
||||
]
|
||||
tab_bar_right_separator = " · "
|
||||
```
|
||||
|
||||
状态区默认为空。添加 `zoom` 后，活动标签页处于缩放状态时会显示固定的 `ZOOM` 标记；它与现有的逐标签页 `Z` 标记相互独立。`hostname`、`datetime` 和 `command` 在 Herdr 服务器上解析，因此使用 `herdr --remote` 时会显示远程机器的值。日期时间条目使用 `strftime` 格式。由于该值是服务器本地的墙上时钟时间，需要 UTC 偏移量或 Unix 时间戳的 `%z`、`%s` 等指令会被拒绝。
|
||||
|
||||
命令条目会立即运行，之后按 `interval_seconds` 刷新，不会阻塞渲染，也不会与上一次运行重叠。间隔范围为 1–31,536,000 秒，超时范围为 1–3,600 秒。Herdr 使用成功输出的最后一行；执行失败、输出为空或超过 `timeout_seconds` 后会清除该值。命令会获得与自定义命令按键绑定相同的活动工作区、标签页、窗格、socket、二进制文件和工作目录上下文。Linux、macOS 和 Windows 均支持命令条目；Linux 和 macOS 使用 `/bin/sh -lc`，Windows 使用 `cmd.exe /d /c`。
|
||||
|
||||
分隔符只会出现在可见条目之间。设置 `tab_bar_right_separator = ""` 可直接连接条目。标签栏较窄时，整个状态区会让位给标签页及其控件。
|
||||
|
||||
### 外层终端窗口标题
|
||||
|
||||
Herdr 会模拟各窗格中的终端，因此窗格内写入的 `OSC 0`/`OSC 2` 标题只会停留在 Herdr。Herdr 会向自己所运行的终端写入自己的标题，窗口管理器和终端标签栏读取的正是这个标题：
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
window_title = "{hostname}: {workspace}"
|
||||
```
|
||||
|
||||
可用记号为 `{hostname}`、`{workspace}`、`{tab}`、`{pane}`（聚焦窗格的手动名称）和 `{terminal_title}`（聚焦窗格自身的终端标题，已去除加载动画字符）。用 `{{` 和 `}}` 表示字面花括号。没有值的记号会渲染为空。
|
||||
|
||||
标题在 Herdr 服务器上生成，因此即使通过 `herdr --remote` 连接或经由 SSH 运行 `herdr`，`{hostname}` 仍然指向运行窗格的那台机器。设置 `window_title = ""` 可以不改动外层终端标题。
|
||||
|
||||
`client.window_title.set` 会覆盖配置的标题，直到 `client.window_title.clear` 将其交还。
|
||||
|
||||
智能体状态默认使用紧凑的彩色圆点。若要同时通过形状和颜色区分 blocked、working、done、idle 与 unknown 状态，请在设置中选择 **distinct symbols**，或配置：
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
status_indicators = "symbols"
|
||||
```
|
||||
|
||||
这些符号是静态的，因此该选项不会启用旋转动画。
|
||||
|
||||
### 侧边栏行布局
|
||||
|
||||
展开的桌面侧边栏会将 `rows` 中的每个内层数组渲染为一行。以下是完整的默认布局：
|
||||
@@ -367,6 +438,8 @@ position = "bottom-right"
|
||||
|
||||
选择 `herdr` 可使用应用内 toast，选择 `terminal` 可使用适合 SSH 场景的外层终端通知，选择 `system` 可使用本地操作系统通知服务，选择 `off` 可禁用弹出通知。Herdr 会抑制活动标签页的弹出通知。在[配置参考](/docs/config-reference/)中搜索 `ui.toast`，可查看位置、延迟行为和剪贴板反馈设置。
|
||||
|
||||
在 macOS 上，`system` 会先尝试 `terminal-notifier`；如果它不可用或执行失败，则回退到 `/usr/bin/osascript`。该回退方式会在通知中心显示为 Script Editor，并且无法激活承载 Herdr 的终端。可运行 `brew install terminal-notifier` 安装 `terminal-notifier`。如果 Herdr 检测到受支持的终端，点击通知时它可以激活该终端应用。也可以选择 `terminal`，让受支持的外层终端负责发送通知。
|
||||
|
||||
## 声音
|
||||
|
||||
声音通知通过本地 Herdr 客户端播放。自定义声音必须是 mp3 文件；相对路径从配置文件所在目录解析。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: 集成
|
||||
description: 为 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Cursor Agent CLI、MastraCode、Antigravity CLI 和 Grok CLI 安装 Herdr 集成。
|
||||
description: 为 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Qwen Code、Cursor Agent CLI、MastraCode、Antigravity CLI 和 Grok CLI 安装 Herdr 集成。
|
||||
---
|
||||
|
||||
Herdr 自动检测受支持的智能体。官方集成可以额外提供用于恢复的原生会话身份、生命周期状态上报,或两者兼有。
|
||||
@@ -25,6 +25,7 @@ herdr integration install kilo
|
||||
herdr integration install hermes
|
||||
herdr integration install mastracode
|
||||
herdr integration install qodercli
|
||||
herdr integration install qwen
|
||||
herdr integration install cursor
|
||||
herdr integration install antigravity-cli
|
||||
herdr integration install grok
|
||||
@@ -46,6 +47,7 @@ herdr integration uninstall kilo
|
||||
herdr integration uninstall hermes
|
||||
herdr integration uninstall mastracode
|
||||
herdr integration uninstall qodercli
|
||||
herdr integration uninstall qwen
|
||||
herdr integration uninstall cursor
|
||||
herdr integration uninstall antigravity-cli
|
||||
herdr integration uninstall grok
|
||||
@@ -58,13 +60,40 @@ Herdr 以两种不同方式使用集成:
|
||||
| 集成类型 | 智能体 | 效果 |
|
||||
| --- | --- | --- |
|
||||
| 生命周期权威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、MastraCode | 已安装且在为该窗格主动上报时,由钩子或插件事件决定 `idle`、`working` 和 `blocked`。对同一个生命周期权威,Herdr 不再使用屏幕清单兜底。 |
|
||||
| 会话身份 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Cursor Agent CLI、Hermes Agent、Antigravity CLI、Grok CLI | 集成上报用于恢复的原生会话引用。状态仍来自 Herdr 的屏幕清单检测。 |
|
||||
| 会话身份 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Qwen Code、Cursor Agent CLI、Hermes Agent、Antigravity CLI、Grok CLI | 集成上报用于恢复的原生会话引用。状态仍来自 Herdr 的屏幕清单检测。 |
|
||||
|
||||
自定义 socket 集成在定义了原生终端 UI 中不可见的状态时,也可以上报状态。
|
||||
自定义集成在定义了原生终端 UI 中不可见的状态时,也可以上报状态。它们不需要内置到 Herdr 中,也不要求 Herdr 识别智能体的可执行文件。
|
||||
|
||||
一些集成会上报智能体的原生会话引用。除非被 `[session] resume_agents_on_restore = false` 禁用,Herdr 会在服务器重启后使用官方会话引用恢复 Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、Grok CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode 和 Antigravity CLI 的窗格。
|
||||
## 集成你自己的智能体
|
||||
|
||||
原生会话恢复需要最新的 Herdr 集成: Pi 集成版本 `2`、OMP 版本 `3`、Claude Code 版本 `6`、Codex 版本 `5`、GitHub Copilot CLI 版本 `2`、Devin CLI 版本 `2`、Droid 版本 `2`、Kimi Code CLI 版本 `3`、Qoder CLI 版本 `2`、Cursor Agent CLI 版本 `1`、Grok CLI 版本 `1`、OpenCode 版本 `5`、Kilo Code CLI 版本 `1`、Hermes Agent 版本 `2`、MastraCode 版本 `1`、Antigravity CLI 版本 `1`。用 `herdr integration status` 查看已安装版本。
|
||||
在 Herdr 窗格中运行的智能体会继承 `HERDR_ENV`、`HERDR_PANE_ID`、`HERDR_BIN_PATH` 和 `HERDR_SOCKET_PATH`。如果智能体提供生命周期钩子,可从这些钩子通过 Herdr CLI 上报语义状态:
|
||||
|
||||
```bash
|
||||
"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
|
||||
--source custom:my-agent \
|
||||
--agent my-agent \
|
||||
--state working
|
||||
```
|
||||
|
||||
当智能体等待输入时上报 `idle`,需要用户决策时上报 `blocked`。用 `--message` 描述阻塞原因。智能体退出时,释放同一来源的生命周期权威:
|
||||
|
||||
```bash
|
||||
"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
|
||||
--source custom:my-agent \
|
||||
--agent my-agent
|
||||
```
|
||||
|
||||
仅在 `HERDR_ENV=1` 且必要变量存在时上报,这样集成在 Herdr 外不会执行任何操作。保持 `--source` 稳定且对该集成唯一。如果上报可能乱序到达,请加入严格递增的 `--seq`;Herdr 会忽略同一来源的旧序列号。
|
||||
|
||||
你可以在 `report-agent` 中加入 `--agent-session-id` 或 `--agent-session-path`,也可以在会话身份独立于状态变化时使用 `pane report-agent-session`。Herdr 会通过窗格和智能体 API 暴露该引用。自动恢复会话还要求 Herdr 知道如何启动该智能体并恢复所引用的会话。
|
||||
|
||||
要实现可移植的集成,请使用 `HERDR_BIN_PATH` 和 CLI 包装命令。需要直接 IPC 的代码可以发送 [Socket API](/zh-cn/docs/socket-api/) 中说明的等效 `pane.report_agent`、`pane.report_agent_session` 和 `pane.release_agent` 请求。
|
||||
|
||||
[Prime Agent 内置的 Herdr 上报器](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/extensions/builtin/herdr-agent-state.ts)是一个真实实现示例。它只在 Herdr 中启用,将智能体事件映射为 `working`、`idle` 和 `blocked`,跨会话保持上报顺序,并在退出时释放权威。
|
||||
|
||||
一些集成会上报智能体的原生会话引用。除非被 `[session] resume_agents_on_restore = false` 禁用,Herdr 会在服务器重启后使用官方会话引用恢复 Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Qwen Code、Cursor Agent CLI、Grok CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode 和 Antigravity CLI 的窗格。
|
||||
|
||||
原生会话恢复需要最新的 Herdr 集成: Pi 集成版本 `2`、OMP 版本 `3`、Claude Code 版本 `6`、Codex 版本 `5`、GitHub Copilot CLI 版本 `2`、Devin CLI 版本 `2`、Droid 版本 `2`、Kimi Code CLI 版本 `3`、Qoder CLI 版本 `2`、Qwen Code 版本 `1`、Cursor Agent CLI 版本 `1`、Grok CLI 版本 `1`、OpenCode 版本 `5`、Kilo Code CLI 版本 `1`、Hermes Agent 版本 `5`、MastraCode 版本 `1`、Antigravity CLI 版本 `1`。用 `herdr integration status` 查看已安装版本。
|
||||
|
||||
## Pi
|
||||
|
||||
@@ -148,7 +177,7 @@ herdr integration install devin
|
||||
|
||||
该钩子从 Devin 的会话、提示、工具使用、权限和停止事件中上报原生会话身份。Devin 的状态仍来自 Herdr 的屏幕清单和 OSC 检测,因为 Devin 钩子不会在每次权限取消或用户中断后都发出可靠的状态转换。
|
||||
|
||||
Herdr 默认使用 `~/.config/devin`,设置了 `XDG_CONFIG_HOME` 时使用 `$XDG_CONFIG_HOME/devin`。Devin 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`,并向 `config.json` 添加 Herdr 钩子条目。钩子在 Devin 运行期间刷新会话引用。卸载会从 `config.json` 中移除 Herdr 条目并删除钩子脚本。
|
||||
Herdr 默认使用 `~/.config/devin`,设置了 `XDG_CONFIG_HOME` 时使用 `$XDG_CONFIG_HOME/devin`。Devin 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`（Windows 上为 `herdr-agent-state.ps1`）,并向 `config.json` 添加 Herdr 钩子条目。钩子在 Devin 运行期间刷新会话引用。卸载会从 `config.json` 中移除 Herdr 条目并删除钩子脚本。
|
||||
|
||||
Herdr 用 `devin --resume <id>` 恢复保存的 Devin 会话。无论钩子是否安装,屏幕清单检测始终是状态权威。
|
||||
|
||||
@@ -212,7 +241,7 @@ Herdr 把插件写入 `~/.config/kilo/plugin/herdr-agent-state.js`。Kilo 配置
|
||||
herdr integration install hermes
|
||||
```
|
||||
|
||||
Herdr 写入 `~/.hermes/plugins/herdr-agent-state/`,并在 `~/.hermes/config.yaml` 中启用 `herdr-agent-state`。Hermes 配置目录必须已经存在。安装后请重启 Hermes 以加载插件。卸载会删除插件目录,并从 `plugins.enabled` 中移除 `herdr-agent-state`。
|
||||
Herdr 写入 Hermes 主目录下的 `plugins/herdr-agent-state/`,并在 Hermes 主目录的 `config.yaml` 中启用 `herdr-agent-state`。`HERMES_HOME` 在 Unix 上默认为 `~/.hermes`,在 Windows 上默认为 `%LOCALAPPDATA%\hermes`。Hermes 配置目录必须已经存在。安装后请重启 Hermes 以加载插件。卸载会删除插件目录,并从 `plugins.enabled` 中移除 `herdr-agent-state`。
|
||||
|
||||
该插件在 Hermes 运行于 Herdr 窗格内时上报可恢复的会话 id。Herdr 使用屏幕清单检测 `working`、`idle` 和 `blocked`,并可用上报的会话 id 通过 `hermes --resume <id>` 恢复该窗格。
|
||||
|
||||
@@ -232,6 +261,20 @@ Herdr 用 `qodercli --resume <id>` 恢复保存的 Qoder CLI 会话。
|
||||
|
||||
钩子未安装时,屏幕清单检测仍然可用。
|
||||
|
||||
## Qwen Code
|
||||
|
||||
安装 Qwen Code 钩子:
|
||||
|
||||
```bash
|
||||
herdr integration install qwen
|
||||
```
|
||||
|
||||
`SessionStart` 钩子只上报用于原生恢复的会话身份。生命周期状态仍由 Herdr 的屏幕清单检测决定。
|
||||
|
||||
Herdr 默认使用 `~/.qwen`,设置了 `QWEN_HOME` 时使用后者。Qwen 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-session.sh`（Windows 上为 `hooks/herdr-agent-session.ps1`）,并向 `settings.json` 添加 Herdr 条目。卸载只移除匹配条目和托管脚本。
|
||||
|
||||
Herdr 用 `qwen --resume <id>` 恢复保存的 Qwen Code 会话。
|
||||
|
||||
## Cursor Agent CLI
|
||||
|
||||
安装 Cursor Agent CLI 钩子:
|
||||
@@ -242,7 +285,7 @@ herdr integration install cursor
|
||||
|
||||
该钩子在 Cursor Agent CLI 运行于 Herdr 窗格内时,通过 Cursor 的 `sessionStart` 钩子上报会话身份。Cursor 的状态来自 Herdr 的屏幕清单检测。
|
||||
|
||||
Herdr 默认使用 `~/.cursor`,设置了 `CURSOR_CONFIG_DIR` 时使用后者。Cursor 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`,并向 `hooks.json` 添加 Herdr 的 `sessionStart` 条目。卸载会移除匹配的钩子条目并删除钩子脚本。
|
||||
Herdr 默认使用 `~/.cursor`,设置了 `CURSOR_CONFIG_DIR` 时使用后者。Cursor 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`（Windows 上为 `herdr-agent-state.ps1`）,并向 `hooks.json` 添加 Herdr 的 `sessionStart` 条目。卸载会移除匹配的钩子条目并删除钩子脚本。
|
||||
|
||||
在 Cursor 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 `cursor-agent --resume <id>` 恢复该窗格。Herdr 恢复窗格时,`cursor-agent` 命令必须在 `PATH` 上;Herdr 不会启动通用的 `agent` 命令。
|
||||
|
||||
@@ -256,7 +299,7 @@ herdr integration install mastracode
|
||||
|
||||
该钩子向 Herdr 上报 MastraCode 生命周期状态和线程身份,用于权威的 `idle`、`working`、`blocked` 状态和原生恢复。MastraCode 没有屏幕清单兜底;当 MastraCode 在 Herdr 窗格内运行时,状态来自该钩子。
|
||||
|
||||
Herdr 使用 `~/.mastracode`。安装会写入 `hooks/herdr-agent-state.sh`,并把 Herdr 命令条目添加到 `hooks.json`;目录不存在时会创建。卸载会删除匹配的钩子条目和钩子脚本。
|
||||
Herdr 使用 `~/.mastracode`。安装会写入 `hooks/herdr-agent-state.sh`（Windows 上为 `hooks/herdr-agent-state.ps1`）,并把 Herdr 命令条目添加到 `hooks.json`;目录不存在时会创建。卸载会删除匹配的钩子条目和钩子脚本。
|
||||
|
||||
Herdr 用 `mastracode --thread <id>` 恢复保存的 MastraCode 线程。
|
||||
|
||||
@@ -284,7 +327,7 @@ herdr integration install grok
|
||||
|
||||
该钩子在 Grok CLI 运行于 Herdr 窗格内时,通过 Grok 的 `SessionStart` 钩子上报会话身份。Grok 的状态来自 Herdr 的屏幕清单检测。
|
||||
|
||||
Herdr 默认使用 `~/.grok`,设置了 `GROK_HOME` 时使用后者。Grok 配置目录必须已经存在。Grok 会合并该目录中的所有 `hooks/*.json` 文件,因此安装会写入独立的 `hooks/herdr.json`,其中包含 Herdr 的 `SessionStart` 条目,并同时写入 `hooks/herdr-agent-state.sh`;它不会修改其他钩子文件。卸载只会删除这两个由 Herdr 管理的文件。
|
||||
Herdr 默认使用 `~/.grok`,设置了 `GROK_HOME` 时使用后者。Grok 配置目录必须已经存在。Grok 会合并该目录中的所有 `hooks/*.json` 文件,因此安装会写入独立的 `hooks/herdr.json`,其中包含 Herdr 的 `SessionStart` 条目,并同时写入 `hooks/herdr-agent-state.sh`（Windows 上为 `hooks/herdr-agent-state.ps1`）;它不会修改其他钩子文件。卸载只会删除这两个由 Herdr 管理的文件。
|
||||
|
||||
Grok 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 `grok --resume <id>` 恢复窗格。
|
||||
|
||||
|
||||
@@ -9,9 +9,10 @@ Herdr 插件市场是一个可供发现的社区插件索引。
|
||||
|
||||
## 浏览插件
|
||||
|
||||
[插件市场](/plugins/)会列出所有打了 GitHub 主题标签 `herdr-plugin` 的公开仓库。
|
||||
你可以按名称、作者、描述或语言搜索,并按热度、最近活跃度或最新排序。
|
||||
每个条目都直接链接到它在 GitHub 上的源码仓库。
|
||||
[插件市场](/plugins/)会列出带有 GitHub 主题标签 `herdr-plugin`,并且默认分支中
|
||||
至少包含一个必需元数据可解析的 `herdr-plugin.toml` 的公开仓库。你可以搜索仓库和
|
||||
插件元数据,并按热度、最近活跃度或最新排序仓库卡片。每张卡片链接到源码仓库,
|
||||
并列出其中发现的所有插件。
|
||||
|
||||
收录是自动且未经审核的。被列出只说明仓库给自己打了标签,并不代表 Herdr
|
||||
审查过它,所以在安装任何插件之前,请先阅读[信任指南](/zh-cn/docs/plugins/#信任与安全)。
|
||||
@@ -30,15 +31,14 @@ herdr plugin install owner/repo[/subdir...]
|
||||
|
||||
## 让你的插件被收录
|
||||
|
||||
给公开仓库添加 GitHub 主题标签 `herdr-plugin`。索引只使用这一个信号,
|
||||
所以给公开插件打上标签就够了。索引每 30 分钟自动刷新,新打标签的仓库很快
|
||||
就会出现,去掉标签的仓库会在下一次刷新时消失。
|
||||
给公开仓库添加 GitHub 主题标签 `herdr-plugin`,并在默认分支中放置一个或多个
|
||||
必需元数据可解析的 `herdr-plugin.toml`。清单可以位于根目录或子目录。插件市场
|
||||
每个仓库显示一张卡片,并把每份有效清单列为可单独安装的插件。索引每 30 分钟
|
||||
自动刷新。
|
||||
|
||||
## 条目会展示什么
|
||||
|
||||
每张卡片展示 GitHub 仓库的元数据: 仓库名和作者、描述、star 数、主要语言、
|
||||
最后 push 时间,以及指回源码的链接。索引从 GitHub 的仓库搜索读取这些信息,
|
||||
所以保持仓库描述和主题标签的准确,是让条目有用的关键。
|
||||
|
||||
索引目前还不会解析 `herdr-plugin.toml`,所以插件 `id`、声明的 `platforms`、
|
||||
`min_herdr_version` 等清单字段在 v1 中不会展示。Fork 和已归档的仓库会被排除。
|
||||
每张卡片展示 GitHub 仓库的名称、作者、描述、star 数、主要语言和最后 push 时间。
|
||||
插件行展示每份清单的 `name` 和 `version`,并链接到精确的源码目录。索引还会记录
|
||||
清单路径、`id`、`name`、`version`、`platforms`、`min_herdr_version`,以及默认分支的
|
||||
精确提交。Fork、已归档仓库、没有有效插件清单的仓库以及无效清单元数据都会被排除。
|
||||
|
||||
@@ -63,11 +63,9 @@ Host workbox
|
||||
herdr --remote workbox
|
||||
```
|
||||
|
||||
远程连接支持 x86_64 和 aarch64 的 Linux 与 macOS 主机。Herdr 会检查远程平台,优先使用远程 `PATH` 上已有的匹配 `herdr`,然后检查 `~/.local/bin/herdr`。如果没有匹配的二进制文件,交互式运行会询问是否安装到 `~/.local/bin/herdr`;非交互式运行则直接失败,不会修改主机。如果 `~/.local/bin` 不在远程 `PATH` 上,Herdr 会在安装后发出警告。
|
||||
远程连接支持 Linux、macOS 和 Windows 本地客户端连接 x86_64 与 aarch64 的 Linux 和 macOS 主机。Herdr 会检查远程平台,优先使用远程 `PATH` 上已有的匹配 `herdr`,然后检查常见的直接安装、Homebrew、mise 和 Nix profile 路径。如果没有匹配的二进制文件,交互式运行会询问是否安装到 `~/.local/bin/herdr`;非交互式运行则直接失败,不会修改主机。如果 `~/.local/bin` 不在远程 `PATH` 上,Herdr 会在安装后发出警告。Windows 不能作为远程主机。
|
||||
|
||||
Windows 原生的 `herdr --remote` 不在 Windows 测试版范围内。在 Windows 上请 SSH 到服务器并在那里运行 `herdr`。
|
||||
|
||||
默认情况下,`herdr --remote` 通过一个临时 SSH 配置运行桥接: 先包含你的 SSH 配置,再补充兜底的保活设置。已有的用户保活设置优先。设置 `[remote].manage_ssh_config = false` 可以不用 Herdr 生成的桥接配置,而使用普通 `ssh`。
|
||||
默认情况下,`herdr --remote` 通过一个临时 SSH 配置运行远程设置和桥接: 先包含你的 SSH 配置,再补充兜底的保活设置。已有的用户保活设置优先。Linux 和 macOS 客户端还会添加一个私有的单次连接 control socket 来复用连接;Windows OpenSSH 不使用此方式。设置 `[remote].manage_ssh_config = false` 可以不用 Herdr 生成的配置或 control socket,而使用普通 `ssh`。
|
||||
|
||||
默认情况下,如果需要替换或重启运行中的远程服务器,远程连接使用常规的重启/停止流程。要对受支持的运行中远程服务器启用实验性实时交接,加上 `--handoff`:
|
||||
|
||||
|
||||
@@ -319,10 +319,12 @@ v1 没有 Herdr 管理的插件存储 API。需要持久状态的插件应自己
|
||||
|
||||
## 插件市场
|
||||
|
||||
社区插件可以在[插件市场](/plugins/)中发现,它是打了 `herdr-plugin` 主题
|
||||
标签的公开 GitHub 仓库的自动索引。插件仍然是普通的 GitHub 仓库: 发布一个
|
||||
带 `herdr-plugin.toml` 的仓库,然后分享
|
||||
社区插件可以在[插件市场](/plugins/)中发现,它是打了 `herdr-plugin` 主题标签且
|
||||
包含一个或多个必需元数据可解析的 `herdr-plugin.toml` 的公开 GitHub 仓库自动索引。
|
||||
插件仍然是普通的 GitHub 仓库: 发布后分享
|
||||
`herdr plugin install owner/repo[/subdir]`。
|
||||
|
||||
要让插件被收录,给它的公开仓库添加 GitHub 主题标签 `herdr-plugin`。索引
|
||||
每 30 分钟刷新一次。发现机制的工作方式见[插件市场](/zh-cn/docs/marketplace/)。
|
||||
要让插件被收录,给公开仓库添加 GitHub 主题标签 `herdr-plugin`,并在默认分支的
|
||||
根目录或子目录放置清单。一张仓库卡片可以包含多个插件。索引每 30 分钟刷新一次。
|
||||
发现机制的工作方式见
|
||||
[插件市场](/zh-cn/docs/marketplace/)。
|
||||
|
||||
@@ -76,6 +76,7 @@ Herdr 只会恢复那些通过当前官方 Herdr 集成上报了原生会话引
|
||||
| Droid | `2` | `droid --resume <id>` |
|
||||
| Kimi Code CLI | `3` | `kimi --session <id>` |
|
||||
| Qoder CLI | `2` | `qodercli --resume <id>` |
|
||||
| Qwen Code | `1` | `qwen --resume <id>` |
|
||||
| OpenCode | `5` | `opencode --session <id>` |
|
||||
| Kilo Code CLI | `1` | `kilo --session <id>` |
|
||||
| Hermes Agent | `2` | `hermes --resume <id>` |
|
||||
|
||||
@@ -107,7 +107,7 @@ herdr pane read w1:p2 --source recent --lines 50
|
||||
| 集成 | `integration.install`、`integration.uninstall` |
|
||||
| 插件 | `plugin.link`、`plugin.list`、`plugin.unlink`、`plugin.enable`、`plugin.disable`、`plugin.action.list`、`plugin.action.invoke`、`plugin.log.list`、`plugin.pane.open`、`plugin.pane.focus`、`plugin.pane.close` |
|
||||
|
||||
`agent.wait` 由服务器拥有并由事件驱动。它会固定到已解析的窗格占用者,因此替换后的智能体不能满足该等待。`agent.prompt` 接受可选的 `wait` 对象,其中包含 `until` 和 `timeout_ms`;这样可在一个请求中提交提示并开始等待,避免两个独立调用之间的竞态。
|
||||
`agent.wait` 由服务器拥有并由事件驱动。它会固定到已解析的窗格占用者,因此替换后的智能体不能满足该等待。`agent.prompt` 接受可选的 `wait` 对象,其中包含 `until` 和 `timeout_ms`;这样可在一个请求中提交提示并开始等待,避免两个独立调用之间的竞态。如果解析出的智能体已经是 `blocked`,`agent.prompt` 不会发送输入或开始等待,而是返回 `agent_blocked`。
|
||||
|
||||
`workspace.move_block` 会将有序的 `workspace_ids` 原子地移动到 `before_workspace_id` 之前;省略锚点则将该块移动到末尾。id 必须唯一,且锚点不能属于被移动的块。响应包含服务器确认的有序工作区列表。
|
||||
|
||||
@@ -273,7 +273,7 @@ herdr notification show "build failed" --body "api workspace" --position top-lef
|
||||
{"id":"req_title_clear","method":"client.window_title.clear","params":{}}
|
||||
```
|
||||
|
||||
`client.window_title.clear` 恢复 Herdr 的默认标题。响应是 `type: "client_window_title"`,带 `changed` 和 `set`、`cleared` 或 `no_foreground_client` 之一的 reason。
|
||||
`client.window_title.clear` 把标题交还给 `ui.window_title`。响应是 `type: "client_window_title"`,带 `changed` 和 `set`、`cleared` 或 `no_foreground_client` 之一的 reason。
|
||||
|
||||
Worktree 方法把 Git 检出作为 Herdr 工作区管理。`worktree.create` 创建检出,并返回新的 `workspace`、`tab`、`root_pane` 和 `worktree` 记录。请求的分支已在本地存在时检出它;否则从请求的 base 或 `HEAD` 创建分支。`worktree.open` 打开已有检出,或返回已打开的工作区。`worktree.remove` 对关联的子工作区运行 `git worktree remove`,从不删除分支。
|
||||
|
||||
|
||||
@@ -26,6 +26,8 @@ Windows 测试版构建只通过预览通道发布。在 Windows 上,Herdr 默
|
||||
| 本地持久会话 | 测试版 |
|
||||
| 通过 ConPTY 的原生窗格 | 测试版 |
|
||||
| Windows Terminal / PowerShell 应用连接 | 测试版 |
|
||||
| 连接 Linux/macOS 主机的 `herdr --remote` | 测试版 |
|
||||
| 远程剪贴板图像和图像文件拖放 | 测试版 |
|
||||
| `cmd.exe` 窗格 | 测试版 |
|
||||
| 启动 cwd 和工作区标签 | 测试版 |
|
||||
| 窗格启动 cwd | 测试版 |
|
||||
@@ -47,14 +49,14 @@ Windows 智能体进程检测会扫描窗格 shell 的后代进程,识别直接
|
||||
| --- | --- |
|
||||
| shell `cd` 之后的实时 cwd | 部分支持 |
|
||||
| 通过 shell 集成/OSC7 的实时 cwd | 测试版 |
|
||||
| 向智能体粘贴剪贴板图像 | 未验证 |
|
||||
| 向本地窗格中的智能体粘贴剪贴板图像 | 未验证 |
|
||||
| CJK 输入法候选窗口定位 | 部分支持 |
|
||||
| Kitty graphics 渲染 | 未验证 |
|
||||
| 主机光标渲染 | 部分支持 |
|
||||
|
||||
Herdr 可以在正确的目录中启动窗格,并能从你启动 Herdr 的目录创建初始工作区。启动之后 PowerShell 的目录变化则不同: Herdr 能检查的进程字段无法可靠跟踪后续的逻辑 `cd` 变化。实时 cwd 上报请使用 Herdr 集成或提示符 shell 集成。
|
||||
|
||||
Windows Terminal 可能为特定智能体支持图像粘贴路径,但 Herdr 自己的剪贴板图像读取器尚未在 Windows 上接通。在 Windows 剪贴板桥实现并测试之前,请把 `alt+v` 图像粘贴视为未验证。远程剪贴板图像桥是独立功能,仍然绑定于 Unix/macOS 的 `herdr --remote`。
|
||||
使用 `herdr --remote` 时,配置的远程图像粘贴键会读取 Windows 剪贴板图像并传输到远程主机。把一个本地图像文件拖入 Windows Terminal 也会传输该文件并粘贴远程路径。向本地原生 Windows 窗格粘贴剪贴板图像仍未验证。
|
||||
|
||||
Kitty graphics 仍是实验性功能,尚未宣称支持 Windows。除非你专门在 Windows Terminal 中测试图像渲染,否则保持 `experimental.kitty_graphics = false`。
|
||||
|
||||
@@ -92,22 +94,20 @@ Herdr 的窗格文本复制在 Windows 测试版上可用。在窗格内拖选
|
||||
| 能力 | 状态 |
|
||||
| --- | --- |
|
||||
| 直接终端附加 | 不支持 |
|
||||
| Windows 二进制的 `herdr --remote` | 不支持 |
|
||||
| Windows 作为 `herdr --remote` 的目标主机 | 不支持 |
|
||||
| 实时服务器交接 | 不支持 |
|
||||
| Unix 文件描述符交接 | 不支持 |
|
||||
| Unix 前台进程组 | 不支持 |
|
||||
| 远程剪贴板图像桥 | 不支持 |
|
||||
| 前缀输入法切换 | 不支持 |
|
||||
| 签名二进制 / 规避 SmartScreen | 不支持 |
|
||||
|
||||
在 Windows 上进行远程工作,请 SSH 到服务器并在那里运行 `herdr`:
|
||||
在 Windows Terminal 中,使用与 Linux 和 macOS 相同的远程命令:
|
||||
|
||||
```powershell
|
||||
ssh you@server
|
||||
herdr
|
||||
herdr --remote workbox
|
||||
```
|
||||
|
||||
这种模式下 Herdr 运行在远程主机上。Windows 原生的 `herdr --remote` 不在测试版范围内。
|
||||
目标主机必须运行 Linux 或 macOS。Herdr 使用已安装的 Windows OpenSSH 客户端和你的 SSH 配置。Windows OpenSSH 不使用 Herdr 的 Unix control socket 连接复用,因此建议通过 Windows `ssh-agent` 使用密钥认证,避免远程设置期间重复提示。
|
||||
|
||||
Windows 更新通过 Windows 安装器进行,并更新带版本号的安装联接点。更新后请重启运行中的 Herdr 会话。实时交接仅限 Unix。
|
||||
|
||||
|
||||
@@ -12,6 +12,24 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "server",
|
||||
"title": "Server",
|
||||
"keys": [
|
||||
{
|
||||
"key": "server.headless_cols",
|
||||
"type": "integer",
|
||||
"default": "120",
|
||||
"description": "Virtual terminal width used for layout and newly created panes when no client is attached. Must be greater than zero."
|
||||
},
|
||||
{
|
||||
"key": "server.headless_rows",
|
||||
"type": "integer",
|
||||
"default": "40",
|
||||
"description": "Virtual terminal height used for layout and newly created panes when no client is attached. Must be greater than zero."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "theme",
|
||||
"title": "Theme",
|
||||
@@ -52,6 +70,24 @@
|
||||
"default": "unset",
|
||||
"description": "Override the panel_bg color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
|
||||
},
|
||||
{
|
||||
"key": "theme.custom.sidebar_bg",
|
||||
"type": "color",
|
||||
"default": "unset",
|
||||
"description": "Set the desktop sidebar background without changing other panel surfaces. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
|
||||
},
|
||||
{
|
||||
"key": "theme.custom.active_row_bg",
|
||||
"type": "color",
|
||||
"default": "unset",
|
||||
"description": "Set the active Space and focused Agent row background without changing separators or scrollbar tracks. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
|
||||
},
|
||||
{
|
||||
"key": "theme.custom.selection_bg",
|
||||
"type": "color",
|
||||
"default": "unset",
|
||||
"description": "Set the Navigate-mode cursor row background in the sidebar without changing other selection surfaces. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
|
||||
},
|
||||
{
|
||||
"key": "theme.custom.surface0",
|
||||
"type": "color",
|
||||
@@ -385,6 +421,18 @@
|
||||
"default": "\"prefix+n\"",
|
||||
"description": "Select the next tab."
|
||||
},
|
||||
{
|
||||
"key": "keys.move_tab_previous",
|
||||
"type": "keybinding",
|
||||
"default": "unset",
|
||||
"description": "Move the active tab one position toward the front. Unset by default."
|
||||
},
|
||||
{
|
||||
"key": "keys.move_tab_next",
|
||||
"type": "keybinding",
|
||||
"default": "unset",
|
||||
"description": "Move the active tab one position toward the back. Unset by default."
|
||||
},
|
||||
{
|
||||
"key": "keys.switch_tab",
|
||||
"type": "keybinding",
|
||||
@@ -517,6 +565,30 @@
|
||||
"default": "\"prefix+r\"",
|
||||
"description": "Enter resize mode."
|
||||
},
|
||||
{
|
||||
"key": "keys.resize_pane_left",
|
||||
"type": "keybinding",
|
||||
"default": "unset",
|
||||
"description": "Resize the focused pane toward the left. Unset by default."
|
||||
},
|
||||
{
|
||||
"key": "keys.resize_pane_down",
|
||||
"type": "keybinding",
|
||||
"default": "unset",
|
||||
"description": "Resize the focused pane downward. Unset by default."
|
||||
},
|
||||
{
|
||||
"key": "keys.resize_pane_up",
|
||||
"type": "keybinding",
|
||||
"default": "unset",
|
||||
"description": "Resize the focused pane upward. Unset by default."
|
||||
},
|
||||
{
|
||||
"key": "keys.resize_pane_right",
|
||||
"type": "keybinding",
|
||||
"default": "unset",
|
||||
"description": "Resize the focused pane toward the right. Unset by default."
|
||||
},
|
||||
{
|
||||
"key": "keys.toggle_sidebar",
|
||||
"type": "keybinding",
|
||||
@@ -652,6 +724,12 @@
|
||||
"default": "true",
|
||||
"description": "Draw borders around split panes."
|
||||
},
|
||||
{
|
||||
"key": "ui.pane_outer_borders",
|
||||
"type": "boolean",
|
||||
"default": "true",
|
||||
"description": "Draw borders along the outside edge of the pane area. Disable with pane gaps disabled for tmux-style internal splitters without an outside frame."
|
||||
},
|
||||
{
|
||||
"key": "ui.pane_scrollbars",
|
||||
"type": "boolean",
|
||||
@@ -686,6 +764,31 @@
|
||||
"bottom"
|
||||
]
|
||||
},
|
||||
{
|
||||
"key": "ui.tab_bar_right",
|
||||
"type": "array",
|
||||
"default": "[]",
|
||||
"description": "Configure ordered right-aligned tab bar entries. Supported types are zoom, hostname, datetime, text, and command.",
|
||||
"values": [
|
||||
"zoom",
|
||||
"hostname",
|
||||
"datetime",
|
||||
"text",
|
||||
"command"
|
||||
]
|
||||
},
|
||||
{
|
||||
"key": "ui.tab_bar_right_separator",
|
||||
"type": "string",
|
||||
"default": "\" \"",
|
||||
"description": "Text inserted between visible right-aligned tab bar entries."
|
||||
},
|
||||
{
|
||||
"key": "ui.window_title",
|
||||
"type": "string",
|
||||
"default": "\"{hostname}: {workspace}\"",
|
||||
"description": "Title Herdr writes to the terminal it runs in. Tokens: {hostname}, {workspace}, {tab}, {pane}, {terminal_title}. Empty leaves the outer title alone."
|
||||
},
|
||||
{
|
||||
"key": "ui.agent_panel_sort",
|
||||
"type": "enum",
|
||||
@@ -696,6 +799,16 @@
|
||||
"priority"
|
||||
]
|
||||
},
|
||||
{
|
||||
"key": "ui.status_indicators",
|
||||
"type": "enum",
|
||||
"default": "\"dots\"",
|
||||
"description": "Choose compact color dots or distinct static symbols for agent states.",
|
||||
"values": [
|
||||
"dots",
|
||||
"symbols"
|
||||
]
|
||||
},
|
||||
{
|
||||
"key": "ui.sidebar.agents.row_gap",
|
||||
"type": "integer",
|
||||
@@ -1016,6 +1129,17 @@
|
||||
"off"
|
||||
]
|
||||
},
|
||||
{
|
||||
"key": "ui.sound.agents.qwen",
|
||||
"type": "enum",
|
||||
"default": "\"default\"",
|
||||
"description": "Sound override for detected Qwen Code agents.",
|
||||
"values": [
|
||||
"default",
|
||||
"on",
|
||||
"off"
|
||||
]
|
||||
},
|
||||
{
|
||||
"key": "ui.sound.agents.maki",
|
||||
"type": "enum",
|
||||
@@ -1109,7 +1233,7 @@
|
||||
"key": "experimental.cjk_ime_agents",
|
||||
"type": "list of strings",
|
||||
"default": "[]",
|
||||
"description": "Restrict `reveal_hidden_cursor_for_cjk_ime` to focused panes whose detected agent matches one of these names (case-insensitive). Empty list means apply to any focused pane. Unknown agent names are ignored; if the list contains no valid names, the reveal does not apply. Accepted names: pi, claude, codex, gemini, cursor, devin, cline, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qoder, maki."
|
||||
"description": "Restrict `reveal_hidden_cursor_for_cjk_ime` to focused panes whose detected agent matches one of these names (case-insensitive). Empty list means apply to any focused pane. Unknown agent names are ignored; if the list contains no valid names, the reveal does not apply. Accepted names: pi, claude, codex, gemini, cursor, devin, cline, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qoder, qwen, qwen-code, maki."
|
||||
},
|
||||
{
|
||||
"key": "experimental.cjk_ime_cursor_shape",
|
||||
|
||||
+45
-15
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user