docs: finalize release docs and refresh agent skill
This commit is contained in:
Ogulcan Celik
parent
7c18900346
commit
bc064e9d03
45
CHANGELOG.md
45
CHANGELOG.md
|
|
@ -2,6 +2,51 @@
|
|||
|
||||
## Unreleased
|
||||
|
||||
### Breaking Changes
|
||||
- Installed and linked plugins, including their enabled state, are now global to the current user instead of isolated by Herdr session. Plugins installed only in a named session on Herdr 0.7.3 must be installed or linked again. (#1174)
|
||||
|
||||
### Added
|
||||
- Added a live-agent CLI facade with named `start`, atomic `prompt`, logical `send-keys`, and server-owned `wait` workflows. Agent startup targets an existing pane without changing topology, validates the requested interactive agent kind and strict agent name, and accepts native arguments after `--`.
|
||||
- Added transient declarative Agent view queries through `agent.view.set/clear`; filtered and sorted views now define sidebar, mobile, mouse, and agent-keybind navigation order.
|
||||
- Added one-shot plugin `[[startup]]` hooks for restoring plugin-owned state after server startup and live handoff.
|
||||
- Added per-token foreground, bold, and dim styling to expanded Space and Agent sidebar row layouts.
|
||||
- Added `ui.sidebar_start_collapsed` to launch Herdr with the sidebar collapsed. (#1463)
|
||||
- Added `ui.prompt_new_workspace_name` to ask for a workspace name before interactive TUI creation.
|
||||
- Added macOS support for the `HERDR_AGENT=<agent>` foreground-process hint, allowing agents hidden behind host-visible wrappers such as `nono` to use the named agent's screen manifest. (#679)
|
||||
|
||||
### Changed
|
||||
- Agent commands now accept only a unique live agent name or the pane ID currently hosting that agent. Names are cleared when the occupant exits, is released, or is replaced. The old top-level `wait` commands were replaced by `agent wait` and `pane wait-output`, and `agent send` was replaced by `agent send-keys`.
|
||||
- The session navigator now uses connected tree glyphs, groups matches by workspace, and automatically selects the first result when a search begins. (#1611)
|
||||
|
||||
### Fixed
|
||||
- CLI requests now return a machine-readable `protocol_mismatch` error when the client and server protocols differ, while recovery commands remain available. (#1435)
|
||||
- Linux sound notifications now terminate and reap audio players that do not exit, preventing unavailable audio from leaving CPU-bound `mpg123` processes behind. (#1622)
|
||||
- Oversized bracketed text pastes are now rejected with a client-local notification instead of disconnecting the client. (#1665)
|
||||
- Agent prompt waits now report `agent_prompt_stalled` after five seconds without an observed state change instead of waiting indefinitely after an ineffective submission.
|
||||
- `herdr config check` now reports unknown config keys with their full paths instead of treating ignored typos as valid configuration. (#1573)
|
||||
- Codex panes with customized static terminal titles now fall back to the live working footer instead of remaining idle, while OSC activity remains preferred. (#1563)
|
||||
- Grok panes now preserve working and blocked state from terminal signals and pinned background-work status instead of falling back to idle mid-turn.
|
||||
- OpenCode lifecycle reports are now serialized so out-of-order plugin events cannot leave an idle pane marked working. (#1519)
|
||||
- Kimi question prompts now report blocked until the user answers or dismisses them.
|
||||
- Pi lifecycle reporting now uses settled events, preventing transient message boundaries from publishing an idle state mid-turn.
|
||||
- The Pi, OMP, OpenCode, and Kilo Code integrations can now be installed on Windows and report lifecycle state and native session identity through Herdr's named-pipe API. (#1531)
|
||||
- Named agent prompts now honor live bracketed-paste mode before sending Enter, preserving OpenCode text such as `A != B` instead of triggering shell mode. (#1525)
|
||||
- New panes, tabs, layouts, and workspaces using `new_cwd = "follow"` now inherit the foreground process-group leader's working directory instead of an unrelated helper process directory. (#1472)
|
||||
- Cached pane working directories no longer trigger repeated filesystem checks, avoiding slow sidebar rendering on network filesystems such as Ceph. (#1603)
|
||||
- Windows foreground-process snapshots are now shared across panes, reducing idle CPU use in sessions with many panes. (#1158)
|
||||
- Terminal diff streams now batch contiguous writes, reducing the visible wave effect while scrolling pane history. (#283)
|
||||
- A standalone Escape arriving beside another key is now preserved as its own input instead of being combined into a fabricated Alt chord. (#541)
|
||||
- Pane viewports that were following live output now continue following after a resize.
|
||||
- Mouse selections now remain visible when `ui.copy_on_select = false` while clipboard writes stay disabled. (#1471)
|
||||
- Workspace close confirmation now shows the current workspace name instead of a stale or unrelated label. (#1364)
|
||||
- Plugin command arrays now preserve whitespace-only arguments. (#1594, #1613)
|
||||
- Plugins can now be installed or linked while no Herdr server is running. (#1670)
|
||||
- Remote attach now discovers Herdr installed in mise's canonical tool path before offering to install a sidecar binary. (#1201)
|
||||
- Noninteractive update, plugin, integration, sound, custom-command, and Git subprocesses no longer flash console windows on Windows. (#1468)
|
||||
- Live handoff now preserves installed plugins and no longer lets the next plugin installation overwrite the existing registry. (#893)
|
||||
- `herdr agent wait` now returns `agent_not_running` promptly when its target pane closes instead of waiting for the full timeout. (#1439)
|
||||
- Pane graphics streams now shut down cleanly when a client disconnect races stream teardown.
|
||||
|
||||
## [0.7.4] - 2026-07-15
|
||||
|
||||
### Added
|
||||
|
|
|
|||
158
SKILL.md
158
SKILL.md
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
name: herdr
|
||||
description: "Control Herdr, a terminal multiplexer for coding agents. Use only when the user explicitly mentions Herdr or asks to use Herdr to inspect or control panes, tabs, workspaces, terminals, commands, or communication with another agent. Do not use merely because a task could benefit from a background terminal, delegation, or parallel work. Requires HERDR_ENV=1."
|
||||
description: "Control Herdr, a terminal multiplexer for coding agents. Use only when the user explicitly mentions Herdr or asks to use Herdr to inspect or control panes, tabs, workspaces, commands, or another agent. Do not use merely because a task could benefit from a background terminal, delegation, or parallel work. Requires HERDR_ENV=1."
|
||||
---
|
||||
|
||||
# Herdr
|
||||
|
||||
Herdr is a terminal multiplexer and runtime for coding agents. It organizes terminals into workspaces, tabs, and panes, detects agent identity and status, and exposes the running session through the `herdr` CLI.
|
||||
Herdr organizes terminals into workspaces, tabs, and panes, recognizes coding agents running inside panes, and exposes the current session through the `herdr` CLI.
|
||||
|
||||
Before issuing any control command, check that this agent is running inside a Herdr-managed pane:
|
||||
Before issuing any control command, verify that this agent is running inside a Herdr-managed pane:
|
||||
|
||||
```bash
|
||||
test "${HERDR_ENV:-}" = 1
|
||||
|
|
@ -15,54 +15,65 @@ test "${HERDR_ENV:-}" = 1
|
|||
|
||||
If the check fails, say that you are not running inside Herdr and stop. Do not inspect or control the focused Herdr session from outside Herdr.
|
||||
|
||||
When the check passes, the `herdr` binary in `PATH` talks to the running session. Use it to inspect neighboring work, create isolated terminal contexts, start agents and commands, read their output, and wait for state changes.
|
||||
When the check passes, the `herdr` binary in `PATH` talks to the current session. Use it to inspect neighboring work, create terminal layout, start agents and commands, read output, and wait for state changes.
|
||||
|
||||
## Learn the current CLI
|
||||
|
||||
The installed binary is the authority for command syntax. Begin with:
|
||||
The installed binary is the authority for command syntax. Start with:
|
||||
|
||||
```bash
|
||||
herdr --help
|
||||
```
|
||||
|
||||
Then print the relevant command group by running it without a subcommand:
|
||||
Then print the relevant command group by running the group without a subcommand:
|
||||
|
||||
```bash
|
||||
herdr agent
|
||||
herdr pane
|
||||
herdr workspace
|
||||
herdr worktree
|
||||
herdr tab
|
||||
herdr wait
|
||||
herdr worktree
|
||||
herdr terminal
|
||||
herdr notification
|
||||
herdr integration
|
||||
herdr session
|
||||
```
|
||||
|
||||
Do not run bare `herdr` for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments; some commands, including `herdr workspace create`, are valid with defaults and will execute. Use the command-group output above instead.
|
||||
Do not run bare `herdr` for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments. Commands such as `herdr workspace create` are valid with defaults and will execute.
|
||||
|
||||
Most control commands print JSON. Read identifiers and state from those responses instead of predicting either one.
|
||||
Most control commands return JSON. Read identifiers and state from those responses instead of predicting them.
|
||||
|
||||
## IDs and current context
|
||||
## Understand layout, panes, and agents
|
||||
|
||||
Public IDs are short stable handles:
|
||||
Choose the primitive that matches the job:
|
||||
|
||||
- Workspace, tab, and pane topology organize terminal locations.
|
||||
- Pane commands control raw terminals, shells, tests, servers, input, and output.
|
||||
- Agent commands control the recognized coding agent currently occupying a pane.
|
||||
|
||||
A pane exists whether or not it contains an agent. `agent start` requires an existing available shell pane and never creates, splits, or moves layout. Use pane commands for ordinary processes. Use agent commands when Herdr must validate agent identity or interpret `idle`, `working`, `blocked`, `done`, and `unknown` lifecycle states.
|
||||
|
||||
Agent commands accept either a unique live agent name or the pane ID currently hosting that agent. They do not accept terminal IDs or bare agent-kind labels. Names must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced.
|
||||
|
||||
`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 unseen background work finishes. Focusing the tab or targeting the pane or agent with a focus command marks it seen. CLI reads do not mark it seen. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently; it does not prove completion.
|
||||
|
||||
## Use IDs and caller context
|
||||
|
||||
Public IDs are opaque stable handles:
|
||||
|
||||
- workspace: `w1`
|
||||
- tab: `w1:t1`
|
||||
- pane: `w1:p1`
|
||||
- terminal: `term_...`
|
||||
|
||||
The encoded suffix can contain letters and can grow beyond one character. Treat every ID as an opaque string.
|
||||
Closed tab and pane IDs are not reused. A pane moved into another workspace receives a new workspace-qualified pane ID. After `pane move`, continue with `.result.move_result.pane.pane_id` or the live agent name. The old value is reported as `.result.move_result.previous_pane_id`; only the moved process's inherited caller context keeps resolving that old ID, so do not use it as a general agent target.
|
||||
|
||||
Closed tab and pane IDs are not reused and do not retarget later resources. A pane moved into another workspace receives a new public pane ID. Re-read create, split, move, list, or get responses after mutations; never construct an ID from a workspace or display number.
|
||||
|
||||
Herdr injects the caller's stable context into every managed pane:
|
||||
Herdr injects the caller's context into each managed pane:
|
||||
|
||||
```bash
|
||||
printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"
|
||||
```
|
||||
|
||||
Prefer `--current` when a pane command should target the calling pane. Omitting a target can use the UI-focused pane, which may belong to the user or another client.
|
||||
Prefer `--current` when a pane command should target the calling pane. Omitting a target may use the UI-focused pane, which can belong to the user or another client.
|
||||
|
||||
Discover live state with:
|
||||
|
||||
|
|
@ -71,125 +82,112 @@ herdr workspace list
|
|||
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
|
||||
herdr pane current --current
|
||||
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
|
||||
herdr agent list
|
||||
```
|
||||
|
||||
## Control agents through panes
|
||||
Creation responses expose the IDs to use next. `workspace create` returns `.result.workspace`, `.result.tab`, and `.result.root_pane`. `tab create` returns `.result.tab` and `.result.root_pane`. `pane split` returns the new pane as `.result.pane`.
|
||||
|
||||
An agent runs inside a pane. Use the pane ID as the control target for agents, shells, servers, tests, and logs. This keeps spawning, input, reads, waits, and cleanup on one stable control surface.
|
||||
## Start and coordinate an agent
|
||||
|
||||
Use workspace and tab commands for organization. Use worktree commands only when you intentionally want Herdr to create, open, or remove a Git checkout.
|
||||
Default to a sibling pane in the current tab and the current working directory. Do not create a workspace, tab, worktree, or different cwd unless the user explicitly requests that topology or location.
|
||||
|
||||
Pane records expose `agent`, `agent_status`, and native session metadata when available. Agent status is `idle`, `working`, `blocked`, `done`, or `unknown`.
|
||||
|
||||
`idle` and `done` are the same underlying semantic state with different attention state:
|
||||
|
||||
- `idle`: the agent is waiting and its result is considered seen.
|
||||
- `done`: the agent finished and its result has not been seen.
|
||||
|
||||
An agent that first opens at its prompt reports `idle`, including in a background pane. After a working or blocked agent completes, it reports `done` when its tab or workspace is in the background. It reports `idle` when it completes in the active tab while the foreground client is focused. If the foreground client is explicitly unfocused, completion can become `done` even in the active tab.
|
||||
|
||||
Focusing a pane, switching to its tab, or regaining outer terminal focus marks the visible tab as seen, so `done` becomes `idle`. Switching away does not turn an existing `idle` status into `done`; `done` is created by a later completion while the pane is unseen. With no foreground client, a new completion in the globally active tab is treated as seen while completions in background tabs still become `done`.
|
||||
|
||||
## Start agents interactively
|
||||
|
||||
Default to a sibling pane in the current tab and current working directory. Do not create a workspace, tab, worktree, or different cwd unless the user explicitly requests that topology or location.
|
||||
|
||||
Honor a direction requested by the user. Otherwise inspect the caller pane's current rectangle:
|
||||
Honor a direction requested by the user. Otherwise inspect the caller pane:
|
||||
|
||||
```bash
|
||||
herdr pane layout --pane "$HERDR_PANE_ID"
|
||||
```
|
||||
|
||||
Split a wide pane to the right and a narrow or tall pane down. Avoid repeated same-direction splits that would create unusably narrow columns or short rows. Keep the user's focus in the calling pane:
|
||||
Split a wide pane to the right and a narrow or tall pane down. Avoid repeated same-direction splits that create unusably narrow columns or short rows. Keep the user's focus in the calling pane and explicitly preserve the caller's working directory:
|
||||
|
||||
```bash
|
||||
herdr pane split --current --direction right --no-focus
|
||||
herdr pane split --current --direction right --cwd "$PWD" --no-focus
|
||||
```
|
||||
|
||||
Replace `right` with `down` when the layout calls for it.
|
||||
Replace `right` with `down` when appropriate. Read the new pane ID from `.result.pane.pane_id`.
|
||||
|
||||
Read `result.pane.pane_id` from the JSON response. Give the pane a useful label, then start the requested agent by running only its normal executable so its interactive TUI opens:
|
||||
An available shell pane must be at its interactive prompt, with the shell itself in the foreground and no foreground command, editor, or agent running. Start a supported agent in that pane with a useful unique name:
|
||||
|
||||
```bash
|
||||
herdr pane rename <returned-pane-id> "reviewer"
|
||||
herdr pane run <returned-pane-id> "codex"
|
||||
herdr agent start reviewer --kind codex --pane <returned-pane-id>
|
||||
```
|
||||
|
||||
Use the executable that belongs to the requested agent:
|
||||
|
||||
- Codex: `codex`
|
||||
- Claude Code: `claude`
|
||||
- pi: `pi`
|
||||
- OpenCode: `opencode`
|
||||
- OMP: `omp`
|
||||
|
||||
Do not pass the task as an argv prompt by default. Do not add non-interactive flags. Only change the normal interactive launch when the user explicitly asks for a different launch mode or command.
|
||||
|
||||
Inspect the pane after launch. If `agent_status` is not yet `idle`, wait for the idle transition. Once it is idle, submit the task with `pane run`:
|
||||
Use the kind requested by the user. Run `herdr agent` to inspect the installed kind list and options. Pass native agent arguments only after `--`:
|
||||
|
||||
```bash
|
||||
herdr pane get <returned-pane-id>
|
||||
herdr wait agent-status <returned-pane-id> --status idle --timeout 30000
|
||||
herdr pane run <returned-pane-id> "Review the current diff and report only actionable findings."
|
||||
herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>
|
||||
```
|
||||
|
||||
Status waits match the current status immediately or wait for a future matching transition.
|
||||
`agent start` returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input. It defaults to a 30-second startup timeout.
|
||||
|
||||
`pane run` sends the text and Enter together. Use it for initial prompts and follow-ups instead of coordinating `send-text` and `send-keys` separately.
|
||||
|
||||
For normal background work, wait for the agent to start working. If the pane remains in a background tab or workspace, wait for `done` before reading its transcript:
|
||||
Submit work through the agent surface:
|
||||
|
||||
```bash
|
||||
herdr wait agent-status <returned-pane-id> --status working --timeout 30000
|
||||
herdr wait agent-status <returned-pane-id> --status done --timeout 120000
|
||||
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120
|
||||
herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
|
||||
```
|
||||
|
||||
If the user is watching that tab, completion reports `idle` instead, so wait for `idle`. Always treat either `idle` or `done` as completed when inspecting `pane get`; the difference is whether the result has been seen.
|
||||
`agent prompt` atomically submits text and encoded Enter while honoring the pane's live bracketed-paste mode. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state. Do not repeat those defaults with `--until`.
|
||||
|
||||
If a wait times out, inspect `herdr pane get <returned-pane-id>` and `pane read` before deciding what to do. A `blocked` agent needs input; an `unknown` pane may not yet contain a detected or integrated agent.
|
||||
A prompt sent from a non-working state must produce an observed lifecycle change within five seconds. Otherwise Herdr returns `agent_prompt_stalled` instead of waiting indefinitely. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it.
|
||||
|
||||
Submit follow-ups the same way:
|
||||
Use `--until` only for a state-specific workflow, such as waiting for an already-running agent to request input:
|
||||
|
||||
```bash
|
||||
herdr pane run <returned-pane-id> "Now check the failing test."
|
||||
herdr agent wait reviewer --until blocked --timeout 120000
|
||||
```
|
||||
|
||||
Without `--until`, standalone `agent wait` uses the same settled-state defaults as `agent prompt --wait`.
|
||||
|
||||
Use logical keys for interactive agent UI controls:
|
||||
|
||||
```bash
|
||||
herdr agent send-keys reviewer esc
|
||||
herdr agent send-keys reviewer ctrl+c
|
||||
```
|
||||
|
||||
Herdr validates all keys before writing any bytes. Read the result through the resolved agent:
|
||||
|
||||
```bash
|
||||
herdr agent get reviewer
|
||||
herdr agent read reviewer --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
If a wait fails or returns `blocked`, inspect `agent get` and `agent read` before deciding what input to send. Use the pane surface only when raw terminal control is intentional.
|
||||
|
||||
## Run an ordinary command in another pane
|
||||
|
||||
Split the calling pane using the same geometry rule without moving the user's focus:
|
||||
Create a sibling pane with the same geometry rule, preserve the caller's working directory, and keep user focus unchanged:
|
||||
|
||||
```bash
|
||||
herdr pane split --current --direction right --no-focus
|
||||
herdr pane split --current --direction right --cwd "$PWD" --no-focus
|
||||
```
|
||||
|
||||
Read the new `pane_id` from the JSON response, then run and inspect the command:
|
||||
Read the new pane ID from `.result.pane.pane_id`, then run and inspect the command:
|
||||
|
||||
```bash
|
||||
herdr pane run <returned-pane-id> "just test"
|
||||
herdr wait output <returned-pane-id> --match "test result" --timeout 120000
|
||||
herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
|
||||
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
Inspect existing output before waiting for future output. A wait timeout exits with status `1`.
|
||||
`pane run` atomically sends command text and Enter. `pane wait-output` searches the selected snapshot immediately, so output that already exists can match. Use `--match <text>` for a literal substring or `--regex <pattern>` for a Rust regular expression. Omitting `--timeout` allows an indefinite wait.
|
||||
|
||||
Use the read source that matches the task:
|
||||
|
||||
- `visible`: the current rendered viewport
|
||||
- `recent`: recent scrollback as rendered, including soft wraps
|
||||
- `recent-unwrapped`: recent scrollback with soft wraps joined; prefer it for logs and transcripts
|
||||
- `detection`: the bottom-buffer snapshot used by agent detection
|
||||
- `visible`: the currently rendered viewport.
|
||||
- `recent`: recent rendered output, including soft wraps.
|
||||
- `recent-unwrapped`: recent output with soft wraps joined; prefer it for logs and transcripts.
|
||||
- `detection`: the plain-text bottom-buffer snapshot used for agent detection.
|
||||
|
||||
Use `--format ansi` when colors and terminal styling are evidence. Otherwise use text.
|
||||
|
||||
If the user explicitly asks for another tab, workspace, or worktree, discover that command group and use returned IDs. Do not infer a larger topology from a request to start an agent or command.
|
||||
Full-screen agents may use the terminal alternate screen. Rows that disappear from that screen do not enter Herdr's host scrollback, so `recent`, `recent-unwrapped`, and larger `--lines` values cannot recover them. Enlarge the pane, request concise output, use the agent's transcript controls, or scroll inside the agent and read `--source visible`.
|
||||
|
||||
## Safety and coordination rules
|
||||
|
||||
- Use `--no-focus` for background work unless the user asked to switch context.
|
||||
- Use `--current` or an explicit ID. Do not rely on another client's focused pane.
|
||||
- Use `--current`, an explicit pane ID, or a unique agent name. Do not rely on another client's focused pane.
|
||||
- Parse IDs from JSON responses. Do not derive them from sidebar order or examples.
|
||||
- Inspect before waiting. Read current output first, then wait for the next state or output you expect.
|
||||
- Do not close workspaces, tabs, panes, or sessions you did not create unless the user explicitly asked.
|
||||
- Never run `herdr server stop` from an active session unless the user explicitly intends to stop the server and its pane processes.
|
||||
- Never kill the main Herdr process. Use named test sessions for experiments that need an isolated server.
|
||||
- CLI server errors are JSON on stderr with exit status 1. CLI syntax errors exit with status 2.
|
||||
|
|
|
|||
|
|
@ -2,35 +2,57 @@
|
|||
|
||||
## Unreleased
|
||||
|
||||
### Breaking Changes
|
||||
- Installed and linked plugins, including their enabled state, are now global to the current user instead of isolated by Herdr session. Plugins installed only in a named session on Herdr 0.7.3 must be installed or linked again. (#1174)
|
||||
|
||||
### Added
|
||||
- Added a live-agent CLI facade with named `start`, atomic `prompt`, logical `send-keys`, and server-owned `wait` workflows. Agent startup targets an existing pane without changing topology, validates the requested interactive agent kind and strict agent name, and accepts native arguments after `--`.
|
||||
- Added transient declarative Agent view queries through `agent.view.set/clear`; filtered and sorted views now define sidebar, mobile, mouse, and agent-keybind navigation order.
|
||||
- Added one-shot plugin `[[startup]]` hooks for restoring plugin-owned state after server startup and live handoff.
|
||||
- Added per-token foreground, bold, and dim styling to expanded Space and Agent sidebar row layouts.
|
||||
- Added `ui.sidebar_start_collapsed` to launch Herdr with the sidebar collapsed. (#1463)
|
||||
- Added `ui.prompt_new_workspace_name` to ask for a workspace name before interactive TUI creation.
|
||||
- Added macOS support for the `HERDR_AGENT=<agent>` foreground-process hint, allowing agents hidden behind host-visible wrappers such as `nono` to use the named agent's screen manifest. (#679)
|
||||
|
||||
### Changed
|
||||
- Agent commands now accept only a unique live agent name or the pane ID currently hosting that agent. Names are cleared when the occupant exits, is released, or is replaced. The old top-level `wait` commands were replaced by `agent wait` and `pane wait-output`, and `agent send` was replaced by `agent send-keys`.
|
||||
- The session navigator now uses connected tree glyphs, groups matches by workspace, and automatically selects the first result when a search begins. (#1611)
|
||||
|
||||
### Fixed
|
||||
- CLI requests now return a machine-readable `protocol_mismatch` error when the client and server protocols differ, while recovery commands remain available. (#1435)
|
||||
- Linux sound notifications now terminate and reap audio players that do not exit, preventing unavailable audio from leaving CPU-bound `mpg123` processes behind. (#1622)
|
||||
- Oversized bracketed text pastes are now rejected with a client-local notification instead of disconnecting the client. (#1665)
|
||||
- Agent prompt waits now report `agent_prompt_stalled` after five seconds without an observed state change instead of waiting indefinitely after an ineffective submission.
|
||||
- `herdr config check` now reports unknown config keys with their full paths instead of treating ignored typos as valid configuration. (#1573)
|
||||
- Codex panes with customized static terminal titles now fall back to the live working footer instead of remaining idle, while OSC activity remains preferred. (#1563)
|
||||
- Grok panes now preserve working and blocked state from terminal signals and pinned background-work status instead of falling back to idle mid-turn.
|
||||
- OpenCode lifecycle reports are now serialized so out-of-order plugin events cannot leave an idle pane marked working. (#1519)
|
||||
- Kimi question prompts now report blocked until the user answers or dismisses them.
|
||||
- Pi lifecycle reporting now uses settled events, preventing transient message boundaries from publishing an idle state mid-turn.
|
||||
- The Pi, OMP, OpenCode, and Kilo Code integrations can now be installed on Windows and report lifecycle state and native session identity through Herdr's named-pipe API. (#1531)
|
||||
- Named agent prompts now honor live bracketed-paste mode before sending Enter, preserving OpenCode text such as `A != B` instead of triggering shell mode. (#1525)
|
||||
- New panes, tabs, layouts, and workspaces using `new_cwd = "follow"` now inherit the foreground process-group leader's working directory instead of an unrelated helper process directory. (#1472)
|
||||
- Cached pane working directories no longer trigger repeated filesystem checks, avoiding slow sidebar rendering on network filesystems such as Ceph. (#1603)
|
||||
- Windows foreground-process snapshots are now shared across panes, reducing idle CPU use in sessions with many panes. (#1158)
|
||||
- Terminal diff streams now batch contiguous writes, reducing the visible wave effect while scrolling pane history. (#283)
|
||||
- A standalone Escape arriving beside another key is now preserved as its own input instead of being combined into a fabricated Alt chord. (#541)
|
||||
- Pane viewports that were following live output now continue following after a resize.
|
||||
- Mouse selections now remain visible when `ui.copy_on_select = false` while clipboard writes stay disabled. (#1471)
|
||||
- Workspace close confirmation now shows the current workspace name instead of a stale or unrelated label. (#1364)
|
||||
- Plugin command arrays now preserve whitespace-only arguments. (#1594, #1613)
|
||||
- Plugins can now be installed or linked while no Herdr server is running. (#1670)
|
||||
- Remote attach now discovers Herdr installed in mise's canonical tool path before offering to install a sidecar binary. (#1201)
|
||||
- Noninteractive update, plugin, integration, sound, custom-command, and Git subprocesses no longer flash console windows on Windows. (#1468)
|
||||
- Live handoff now preserves installed plugins and no longer lets the next plugin installation overwrite the existing registry. (#893)
|
||||
- `herdr wait agent-status` now returns `pane_not_found` promptly when its target pane closes instead of waiting for the full timeout. (#1439)
|
||||
- `herdr agent wait` now returns `agent_not_running` promptly when its target pane closes instead of waiting for the full timeout. (#1439)
|
||||
- Pane graphics streams now shut down cleanly when a client disconnect races stream teardown.
|
||||
|
||||
## [0.7.4] - 2026-07-15
|
||||
|
||||
### Added
|
||||
- Added session-modal popup floating terminal panes for `type = "popup"` custom command keybindings and plugin panes, with optional cell or percentage sizing and no changes to the tiled tab layout. (#1125)
|
||||
- Added `ui.copy_on_select` to disable automatic clipboard copying after mouse selection while keeping the selection visible.
|
||||
- Added configurable row layouts and per-occurrence foreground, bold, and dim styles for expanded Space and Agent sidebar entries, including built-in display tokens, per-agent overrides, custom metadata tokens, and pane/workspace metadata reporting through the CLI and socket API.
|
||||
- Added configurable row layouts for expanded Space and Agent sidebar entries, including built-in display tokens, per-agent overrides, custom metadata tokens, and pane/workspace metadata reporting through the CLI and socket API.
|
||||
- Added independent `row_gap` settings for expanded Space and Agent sidebar entries.
|
||||
- Copy mode now supports literal smart-case search with `/` and `?`, repeating with `n` and `N`, match highlighting, and tmux-style cross-line `w`/`b`/`e` word motions. (#1230)
|
||||
- Added Maki agent support. (#1301, #1302, thanks @tontinton)
|
||||
|
|
|
|||
|
|
@ -49,13 +49,6 @@ An available shell pane is at its interactive shell prompt: the shell itself own
|
|||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
```
|
||||
|
||||
The equivalent fixed-ID example is:
|
||||
|
||||
```bash
|
||||
herdr pane split --current --direction right --no-focus
|
||||
herdr agent start reviewer --kind codex --pane w1:p2 -- -m gpt-5.4
|
||||
```
|
||||
|
||||
Agents launched manually are detected automatically and can be addressed by pane ID. Give one a name when a stable human-readable target is useful:
|
||||
|
||||
```bash
|
||||
|
|
@ -84,9 +77,9 @@ Pane input addresses the terminal regardless of its current occupant. Agent inpu
|
|||
|
||||
`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.
|
||||
|
||||
`pane wait-output` does not interpret agent lifecycle. It polls the selected terminal snapshot and searches it immediately, so text that was already present can match. The default source name is `recent`; matching treats that source as unwrapped recent output. `--lines` limits the searched snapshot, `--regex` uses Rust regular-expression syntax and matches one line at a time, and `--raw` keeps ANSI escape sequences while matching.
|
||||
`pane wait-output` does not interpret agent lifecycle. It polls the selected terminal snapshot and searches it immediately, so text that was already present can match. The default source name is `recent`; matching treats that source as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit, and `--regex` uses Rust regular-expression syntax and matches one line at a time.
|
||||
|
||||
At the CLI, both `pane read` and `agent read` print terminal text directly. The default is UTF-8 text with ANSI escapes stripped; use `--format ansi` or `--ansi` to preserve terminal escapes where the source exposes them. The `detection` source is always plain text. For every read source, `--lines N` returns the last N logical lines. The socket API returns the text at `.result.read.text`.
|
||||
At the CLI, both `pane read` and `agent read` print terminal text directly. The default is UTF-8 text with ANSI escapes stripped; use `--format ansi` or `--ansi` to preserve terminal escapes where the source exposes them. The `detection` source is always plain text. For recent sources, `--lines N` selects the last N rendered terminal rows before optional unwrapping; without it, reads default to 80 rows. For `visible` and `detection`, omitting `--lines` returns the full snapshot, while specifying it keeps the last N newline-delimited lines. The socket API returns the text at `.result.read.text`.
|
||||
|
||||
## Known caveat: alternate-screen output
|
||||
|
||||
|
|
|
|||
|
|
@ -198,7 +198,7 @@ herdr pane read <pane_id> --source visible --ansi
|
|||
herdr pane read <pane_id> --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
`pane read` prints UTF-8 terminal text directly. ANSI escapes are stripped by default; use `--format ansi` or `--ansi` to preserve them where the source exposes styling. The `detection` source is always plain text. For every source, `--lines N` returns the last N logical lines. `agent read` uses the same output and line behavior.
|
||||
`pane read` prints UTF-8 terminal text directly. ANSI escapes are stripped by default; use `--format ansi` or `--ansi` to preserve them where the source exposes styling. The `detection` source is always plain text. For recent sources, `--lines N` selects the last N rendered terminal rows before optional unwrapping; without it, reads default to 80 rows. For `visible` and `detection`, omitting `--lines` returns the full snapshot, while specifying it keeps the last N newline-delimited lines. `agent read` uses the same output and line behavior.
|
||||
|
||||
Send input:
|
||||
|
||||
|
|
@ -346,7 +346,7 @@ herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source
|
|||
|
||||
Use `pane wait-output` for normal commands and servers. Use `agent wait` for coding agents.
|
||||
|
||||
`pane wait-output` checks the selected snapshot immediately, including output that already exists, then polls until it matches. The default source name is `recent`; matching treats it as unwrapped recent output with no line limit. `--match` finds a literal substring on one line; `--regex` uses Rust regular-expression syntax and also matches one line at a time. `--raw` keeps ANSI escape sequences instead of stripping them.
|
||||
`pane wait-output` checks the selected snapshot immediately, including output that already exists, then polls until it matches. The default source name is `recent`; matching treats it as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit. `--match` finds a literal substring on one line, and `--regex` uses Rust regular-expression syntax and also matches one line at a time.
|
||||
|
||||
`pane wait-output`, `agent wait`, and `agent prompt --wait` wait indefinitely when `--timeout` is omitted. A timeout or server error is emitted as JSON on stderr with exit status 1. CLI usage errors exit with status 2.
|
||||
|
||||
|
|
|
|||
|
|
@ -49,13 +49,6 @@ review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
|||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
```
|
||||
|
||||
固定 ID を使う同等の例:
|
||||
|
||||
```bash
|
||||
herdr pane split --current --direction right --no-focus
|
||||
herdr agent start reviewer --kind codex --pane w1:p2 -- -m gpt-5.4
|
||||
```
|
||||
|
||||
手動で起動したエージェントも自動検出され、ペイン ID で指定できます。人が読みやすい安定した対象名が必要なら名前を付けます:
|
||||
|
||||
```bash
|
||||
|
|
@ -84,9 +77,9 @@ herdr agent rename w1:p2 reviewer
|
|||
|
||||
`idle` は、エージェントが入力待ちで、そのタブがフォーカス中の Herdr UI ですでに表示済みであることを示します。`done` は同じ基礎的な idle 状態ですが、バックグラウンド作業が完了してから、そのタブをフォーカスするか `pane focus` / `agent focus` で対象にするまで使われます。CLI で読み取るだけでは表示済みになりません。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するもののライフサイクルを確実に分類できない状態で、成功完了を意味しません。違いが重要なら正確な `--until` を指定してください。
|
||||
|
||||
`pane wait-output` はエージェントのライフサイクルを解釈しません。選択したターミナルスナップショットをポーリングし、最初にすぐ検索するため、すでに存在する文字列も一致します。デフォルトのソース名は `recent` で、マッチング時は recent の折り返し前の出力として扱われます。`--lines` は検索範囲を制限し、`--regex` は Rust の正規表現構文で 1 行ずつ一致し、`--raw` は ANSI エスケープシーケンスを残して検索します。
|
||||
`pane wait-output` はエージェントのライフサイクルを解釈しません。選択したターミナルスナップショットをポーリングし、最初にすぐ検索するため、すでに存在する文字列も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更でき、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。
|
||||
|
||||
CLI では、`pane read` と `agent read` のどちらもターミナルテキストを直接出力します。デフォルトは ANSI エスケープを除去した UTF-8 テキストです。ソースに装飾が含まれる場合、`--format ansi` または `--ansi` でエスケープを残します。`detection` ソースは常にプレーンテキストです。すべての read ソースで、`--lines N` は末尾の N 論理行を返します。socket API ではテキストを `.result.read.text` に返します。
|
||||
CLI では、`pane read` と `agent read` のどちらもターミナルテキストを直接出力します。デフォルトは ANSI エスケープを除去した UTF-8 テキストです。ソースに装飾が含まれる場合、`--format ansi` または `--ansi` でエスケープを残します。`detection` ソースは常にプレーンテキストです。recent 系ソースでは、`--lines N` は折り返し解除の前に末尾の N 描画行を選び、省略時は 80 行です。`visible` と `detection` では、省略時にスナップショット全体を返し、指定時は改行で区切られた末尾 N 行を返します。socket API ではテキストを `.result.read.text` に返します。
|
||||
|
||||
## 既知の注意点: 代替画面の出力
|
||||
|
||||
|
|
|
|||
|
|
@ -191,7 +191,7 @@ herdr pane read <pane_id> --source visible --ansi
|
|||
herdr pane read <pane_id> --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
`pane read` は UTF-8 のターミナルテキストを直接出力します。デフォルトでは ANSI エスケープを除去し、ソースに装飾が含まれる場合は `--format ansi` または `--ansi` で保持します。`detection` ソースは常にプレーンテキストです。すべてのソースで `--lines N` は末尾の N 論理行を返します。`agent read` も同じ出力と行数の動作です。
|
||||
`pane read` は UTF-8 のターミナルテキストを直接出力します。デフォルトでは ANSI エスケープを除去し、ソースに装飾が含まれる場合は `--format ansi` または `--ansi` で保持します。`detection` ソースは常にプレーンテキストです。recent 系ソースでは、`--lines N` は折り返し解除の前に末尾の N 描画行を選び、省略時は 80 行です。`visible` と `detection` では、省略時にスナップショット全体を返し、指定時は改行で区切られた末尾 N 行を返します。`agent read` も同じ出力と行数の動作です。
|
||||
|
||||
入力を送る:
|
||||
|
||||
|
|
@ -320,7 +320,7 @@ herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source
|
|||
|
||||
通常のコマンドやサーバーには `pane wait-output` を使います。コーディングエージェントには `agent wait` を使います。
|
||||
|
||||
`pane wait-output` は選択したスナップショットを最初にすぐ検索するため、すでに存在する出力も一致します。デフォルトのソース名は `recent` で、マッチング時は行数制限なしの recent 折り返し前出力として扱われます。`--match` は 1 行内のリテラル部分文字列を検索し、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。`--raw` は ANSI エスケープシーケンスを除去しません。
|
||||
`pane wait-output` は選択したスナップショットを最初にすぐ検索するため、すでに存在する出力も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更できます。`--match` は 1 行内のリテラル部分文字列を検索し、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。
|
||||
|
||||
`pane wait-output`、`agent wait`、`agent prompt --wait` は、`--timeout` を省略すると無期限に待ちます。タイムアウトまたはサーバーエラーは JSON として stderr に出力され、終了コード 1 になります。CLI 使用法のエラーは終了コード 2 です。
|
||||
|
||||
|
|
|
|||
|
|
@ -74,6 +74,9 @@ command = ["npm", "ci"]
|
|||
command = ["npm", "run", "build"]
|
||||
platforms = ["linux", "macos"]
|
||||
|
||||
[[startup]]
|
||||
command = ["node", "dist/restore.js"]
|
||||
|
||||
[[actions]]
|
||||
id = "apply"
|
||||
title = "Apply layout"
|
||||
|
|
@ -110,10 +113,10 @@ ASCII の英字、数字、コロン、アンダースコア、ハイフンが
|
|||
一意な名前が必要なとき、Herdr はアクション id を `plugin.id.action` の形に修飾します。
|
||||
|
||||
プラグインが動作する場所は `platforms = ["linux", "macos", "windows"]` で宣言します。
|
||||
ビルドコマンド、アクション、イベントフック、ペイン、リンクハンドラーも独自の
|
||||
`platforms` を宣言でき、項目レベルの platforms はトップレベルのリストを
|
||||
上書きします。トップレベルの `platforms` がないローカルプラグインは警告付きで
|
||||
リンクされます。
|
||||
ビルドコマンド、スタートアップフック、アクション、イベントフック、ペイン、
|
||||
リンクハンドラーも独自の `platforms` を宣言でき、項目レベルの platforms は
|
||||
トップレベルのリストを上書きします。トップレベルの `platforms` がないローカル
|
||||
プラグインは警告付きでリンクされます。
|
||||
|
||||
`command` の値は argv 配列です。Herdr はこれをシェル経由で実行しないため、
|
||||
コマンド自身がシェルを起動しない限りシェル展開はありません。言語固有の挙動は
|
||||
|
|
@ -192,6 +195,11 @@ herdr plugin log list --plugin example.layout
|
|||
ビルドコマンドを実行し、チェックアウトを Herdr 管理のプラグインデータの下に保存して
|
||||
登録します。非対話的なインストールには `--yes` を使ってください。GitHub 管理の
|
||||
プラグインを再インストールすると、その管理チェックアウトが置き換えられます。
|
||||
インストール済みおよびリンク済みのプラグインと、その有効・無効の状態は現在の
|
||||
ユーザー全体で共有され、すべての Herdr セッションから利用できます。Herdr サーバーが
|
||||
動作していないときでも `plugin install` と `plugin link` で登録できます。
|
||||
Herdr 0.7.3 の名前付きセッションだけにインストールしたプラグインは、再度 install
|
||||
または link してください。既存のプラグイン設定と状態はそのまま残ります。
|
||||
ローカルにリンクされたプラグインへの上書きインストールは拒否されます。先に
|
||||
ローカルプラグインを unlink または uninstall してください。`plugin install` と
|
||||
`plugin link` はプラグインの設定・状態ディレクトリを作成し、
|
||||
|
|
@ -226,6 +234,23 @@ Herdr のソケット環境変数は受け取りません。プラグインの
|
|||
`bun`、`lua` といった必要なシステムツールをドキュメントに書いてください。Herdr は
|
||||
ビルドの失敗を報告しますが、足りないツールチェーンをインストールすることはありません。
|
||||
|
||||
## スタートアップフック
|
||||
|
||||
`[[startup]]` コマンドは、Herdr がセッションを復元し、API ソケットの準備が整った後に、
|
||||
有効なプラグインごとに一度実行されます。ライブハンドオフで新しいサーバーが引き継いだ
|
||||
ときにも再実行されますが、クライアントの接続、設定の再読み込み、プラグインの link や
|
||||
enable では実行されません。Herdr はこれらを非同期で開始し、完了を通常のプラグイン
|
||||
コマンドログに記録します。スタートアップの失敗でサーバーが停止することはありません。
|
||||
|
||||
スタートアップフックは一度限りの初期化コマンドであり、監視されるデーモンではありません。
|
||||
フックはプラグインが所有する状態を復元し、必要な Herdr API を呼び出して終了してください。
|
||||
たとえば宣言型の Agent ビューを `HERDR_PLUGIN_STATE_DIR` に保存し、スタートアップフックで
|
||||
読み込んで再適用できます。
|
||||
|
||||
スタートアップフックは通常のランタイムプラグイン環境と
|
||||
`HERDR_PLUGIN_EVENT=startup` を受け取ります。インストールプレビューには、自動実行される
|
||||
コードを確認できるよう、すべてのスタートアップコマンドが表示されます。
|
||||
|
||||
## コマンドと環境
|
||||
|
||||
ランタイムコマンドは、プラグインディレクトリを作業ディレクトリとして実行されます。
|
||||
|
|
@ -233,8 +258,9 @@ Herdr は `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV=1`、
|
|||
`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、
|
||||
`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_CONTEXT_JSON`、そして利用可能なら
|
||||
`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID` を注入します。アクション
|
||||
コマンドは加えて `HERDR_PLUGIN_ACTION_ID` を受け取ります。イベントフックは
|
||||
`HERDR_PLUGIN_EVENT` と `HERDR_PLUGIN_EVENT_JSON` を、ペインコマンドは
|
||||
コマンドは加えて `HERDR_PLUGIN_ACTION_ID` を受け取ります。スタートアップフックと
|
||||
イベントフックは `HERDR_PLUGIN_EVENT`（スタートアップフックでは `startup`）を受け取り、
|
||||
イベントフックはさらに `HERDR_PLUGIN_EVENT_JSON` を、ペインコマンドは
|
||||
`HERDR_PLUGIN_ENTRYPOINT_ID` を受け取ります。
|
||||
|
||||
`HERDR_PLUGIN_ROOT` は、インストールまたはリンクされたプラグインディレクトリです。
|
||||
|
|
|
|||
|
|
@ -297,6 +297,80 @@ Worktree メソッドは Git チェックアウトを Herdr ワークスペー
|
|||
|
||||
worktree コマンドはライフサイクルイベントも発行します。`worktree.create` は `workspace.created`、`tab.created`、`pane.created`、`worktree.created` を発行します。`worktree.open` は `worktree.opened` を発行し、新しい Herdr ワークスペースを開いた場合はワークスペース/タブ/ペインの作成イベントも発行します。`worktree.remove` は `worktree.removed` を発行し、リンクされたワークスペースがまだ開いている場合は `workspace.closed` も発行します。
|
||||
|
||||
## エージェントビューのクエリ
|
||||
|
||||
`agent.view.set` は、組み込みの Agents ビューに一つの一時的な宣言型プロジェクションを
|
||||
設定します。エージェントの情報や現在の UI コンテキストが変わるたびに再評価されます。
|
||||
展開・折りたたみサイドバー、モバイルの Agents リスト、マウスターゲット、番号付き
|
||||
フォーカス、前後のエージェントへの移動順を制御します。`agent.list`、通知、検出、
|
||||
グローバルな要対応件数は変更しません。
|
||||
|
||||
現在表示中の Space にいるエージェント、または別の場所で対応が必要なエージェントを
|
||||
表示し、要対応度と直近の状態遷移で並べ替える例です:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "view_set",
|
||||
"method": "agent.view.set",
|
||||
"params": {
|
||||
"source": "plugin:example.agent-views",
|
||||
"label": "focus",
|
||||
"filter": {
|
||||
"op": "any",
|
||||
"filters": [
|
||||
{
|
||||
"op": "eq",
|
||||
"field": "workspace_id",
|
||||
"value": {"context": "current_workspace_id"}
|
||||
},
|
||||
{
|
||||
"op": "in",
|
||||
"field": "status",
|
||||
"values": ["blocked", "done"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"sort": [
|
||||
{"field": "attention", "order": "desc"},
|
||||
{"field": "state_change_seq", "order": "desc"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
フィルターノードの `op` には `all`、`any`、`not`、`eq`、`in`、`exists` を使います。
|
||||
組み込みフィールドは `status`、`workspace_id`、`tab_id`、`pane_id`、`agent`、
|
||||
`seen`、`state_change_seq` です。プラグインが報告したペインメタデータを絞り込むには、
|
||||
フィールドとして `{"token":"name"}` を使います。値には文字列、真偽値、符号なし整数、
|
||||
またはコンテキストオブジェクトを指定できます。コンテキスト値は
|
||||
`current_workspace_id` と `current_tab_id` で、対応する ID フィールドとの比較にだけ
|
||||
使えます。有効な status は `idle`、`working`、`blocked`、`done`、`unknown` です。
|
||||
`done` は idle かつ未確認の状態を表します。
|
||||
|
||||
ソートフィールドは `workspace_order`、`tab_order`、`pane_order`、`attention`、
|
||||
`status`、`agent`、`seen`、`state_change_seq`、または `{"token":"name"}` です。
|
||||
ソートは安定しており、指定順に評価され、`asc` または `desc` を受け付けます。値がない
|
||||
項目は値がある項目の後に残ります。`sort` を省略すると既存の
|
||||
`ui.agent_panel_sort` ポリシーが有効です。カスタムソートは設定を書き換えず、一時的に
|
||||
そのポリシーを置き換えます。
|
||||
|
||||
`source` は所有者を識別します。プラグインは `plugin:<HERDR_PLUGIN_ID>` を使います。
|
||||
所有元のプラグインが存在しないか無効な場合、Herdr は設定を拒否します。他の呼び出し元は
|
||||
独自の非 `plugin:` source を使えます。設定に成功すると以前のビューはアトミックに
|
||||
置き換えられます。ビューは clear または置換されるか、所有プラグインが disable、unlink、
|
||||
uninstall されるか、サーバーが終了するまで有効です。永続的な動作が必要なプラグインは、
|
||||
クエリを `HERDR_PLUGIN_STATE_DIR` に保存し、`[[startup]]` フックから再適用してください。
|
||||
|
||||
無条件で clear するか、指定した source がまだ所有している場合だけ clear できます:
|
||||
|
||||
```json
|
||||
{"id":"view_clear","method":"agent.view.clear","params":{}}
|
||||
{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}
|
||||
```
|
||||
|
||||
source が一致しない場合、アクティブなビューは変わりません。set と clear のレスポンスは
|
||||
`type: "agent_view"` で、`active`、`source`、任意の `label` を報告します。
|
||||
|
||||
## プラグイン API
|
||||
|
||||
プラグイン API は、実行可能なワークフローツールのための初期のホスト面です。プラグインは `herdr-plugin.toml` マニフェストを持つパッケージです。マニフェストは、共有可能なアクション、イベントフック、ターミナルペインのエントリーポイント、リンクハンドラーを宣言します。アクションとペインはマニフェスト専用です。ランタイムでのアクション登録とランタイムでの argv ペイン作成は v1 の範囲外です。
|
||||
|
|
|
|||
|
|
@ -49,13 +49,6 @@ review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
|||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
```
|
||||
|
||||
使用固定 ID 的等价示例:
|
||||
|
||||
```bash
|
||||
herdr pane split --current --direction right --no-focus
|
||||
herdr agent start reviewer --kind codex --pane w1:p2 -- -m gpt-5.4
|
||||
```
|
||||
|
||||
手动启动的智能体也会被自动检测,可以用窗格 ID 指定。当需要一个稳定、易读的目标时,给它命名:
|
||||
|
||||
```bash
|
||||
|
|
@ -84,9 +77,9 @@ herdr agent rename w1:p2 reviewer
|
|||
|
||||
`idle` 表示智能体正等待输入,且其标签页已在聚焦的 Herdr 界面中显示。`done` 是相同的底层 idle 状态,但用于后台工作完成后,直到该标签页获得焦点或 `pane focus` / `agent focus` 指向它。仅通过 CLI 读取不会把它标记为已查看。`blocked` 表示 Herdr 识别到了审批或提问界面。`unknown` 表示智能体存在,但 Herdr 无法可靠判断其生命周期;它不代表工作成功完成。区别重要时,请指定精确的 `--until` 状态。
|
||||
|
||||
`pane wait-output` 不解释智能体生命周期。它轮询选定的终端快照并立即进行第一次搜索,所以已经存在的文本也会匹配。默认来源名是 `recent`;匹配时会把它作为 recent 的未折行输出来处理。`--lines` 限制搜索范围;`--regex` 使用 Rust 正则表达式语法并逐行匹配;`--raw` 在匹配时保留 ANSI 转义序列。
|
||||
`pane wait-output` 不解释智能体生命周期。它轮询选定的终端快照并立即进行第一次搜索,所以已经存在的文本也会匹配。默认来源名是 `recent`;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。`--lines` 可以修改这个行数限制;`--regex` 使用 Rust 正则表达式语法并逐行匹配。
|
||||
|
||||
在 CLI 中,`pane read` 和 `agent read` 都直接打印终端文本。默认输出去除 ANSI 转义的 UTF-8 文本;来源包含样式时,使用 `--format ansi` 或 `--ansi` 保留终端转义。`detection` 来源始终是纯文本。对所有 read 来源,`--lines N` 都返回末尾 N 个逻辑行。socket API 在 `.result.read.text` 返回文本。
|
||||
在 CLI 中,`pane read` 和 `agent read` 都直接打印终端文本。默认输出去除 ANSI 转义的 UTF-8 文本;来源包含样式时,使用 `--format ansi` 或 `--ansi` 保留终端转义。`detection` 来源始终是纯文本。对 recent 类来源,`--lines N` 会在可选的取消折行之前选择最后 N 个已渲染终端行;省略时默认读取 80 行。对 `visible` 和 `detection`,省略 `--lines` 会返回完整快照,指定时保留按换行分隔的最后 N 行。socket API 在 `.result.read.text` 返回文本。
|
||||
|
||||
## 已知注意事项:备用屏幕输出
|
||||
|
||||
|
|
|
|||
|
|
@ -191,7 +191,7 @@ herdr pane read <pane_id> --source visible --ansi
|
|||
herdr pane read <pane_id> --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
`pane read` 直接打印 UTF-8 终端文本。默认去除 ANSI 转义;来源包含样式时,使用 `--format ansi` 或 `--ansi` 保留。`detection` 来源始终是纯文本。对所有来源,`--lines N` 都返回末尾 N 个逻辑行。`agent read` 使用相同的输出和行数行为。
|
||||
`pane read` 直接打印 UTF-8 终端文本。默认去除 ANSI 转义;来源包含样式时,使用 `--format ansi` 或 `--ansi` 保留。`detection` 来源始终是纯文本。对 recent 类来源,`--lines N` 会在可选的取消折行之前选择最后 N 个已渲染终端行;省略时默认读取 80 行。对 `visible` 和 `detection`,省略 `--lines` 会返回完整快照,指定时保留按换行分隔的最后 N 行。`agent read` 使用相同的输出和行数行为。
|
||||
|
||||
发送输入:
|
||||
|
||||
|
|
@ -320,7 +320,7 @@ herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source
|
|||
|
||||
普通命令和服务器用 `pane wait-output`。编程智能体用 `agent wait`。
|
||||
|
||||
`pane wait-output` 会立即检查所选快照,所以已经存在的输出也能匹配。默认来源名是 `recent`;匹配时会把它作为不限制行数的 recent 未折行输出。`--match` 在单行中查找字面子串;`--regex` 使用 Rust 正则表达式语法并逐行匹配。`--raw` 保留 ANSI 转义序列。
|
||||
`pane wait-output` 会立即检查所选快照,所以已经存在的输出也能匹配。默认来源名是 `recent`;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。`--lines` 可以修改这个行数限制。`--match` 在单行中查找字面子串;`--regex` 使用 Rust 正则表达式语法并逐行匹配。
|
||||
|
||||
`pane wait-output`、`agent wait` 和 `agent prompt --wait` 在省略 `--timeout` 时会无限等待。超时或服务器错误以 JSON 写到 stderr,退出状态为 1。CLI 用法错误的退出状态为 2。
|
||||
|
||||
|
|
|
|||
|
|
@ -62,6 +62,9 @@ command = ["npm", "ci"]
|
|||
command = ["npm", "run", "build"]
|
||||
platforms = ["linux", "macos"]
|
||||
|
||||
[[startup]]
|
||||
command = ["node", "dist/restore.js"]
|
||||
|
||||
[[actions]]
|
||||
id = "apply"
|
||||
title = "Apply layout"
|
||||
|
|
@ -97,9 +100,9 @@ ASCII 字母、数字、冒号、下划线和连字符,但不能用点。每种
|
|||
`plugin.id.action` 的形式。
|
||||
|
||||
用 `platforms = ["linux", "macos", "windows"]` 声明插件可以运行的平台。
|
||||
构建命令、动作、事件钩子、窗格和链接处理器也可以声明自己的 `platforms`;
|
||||
条目级的 platforms 覆盖顶层列表。没有顶层 `platforms` 的本地插件在链接
|
||||
时会给出警告。
|
||||
构建命令、启动钩子、动作、事件钩子、窗格和链接处理器也可以声明自己的
|
||||
`platforms`;条目级的 platforms 覆盖顶层列表。没有顶层 `platforms` 的本地
|
||||
插件在链接时会给出警告。
|
||||
|
||||
`command` 的值是 argv 数组。Herdr 不会通过 shell 运行它们,所以除非你的
|
||||
命令自己启动 shell,否则没有 shell 展开。语言相关的行为放到你的脚本或
|
||||
|
|
@ -174,8 +177,12 @@ herdr plugin log list --plugin example.layout
|
|||
`plugin install` 只接受 GitHub 简写,比如 `owner/repo/subdir`。它用 `git`
|
||||
克隆,在交互式终端展示预览,运行受支持的构建命令,然后把检出保存到
|
||||
Herdr 管理的插件数据下并注册。非交互式安装用 `--yes`。重新安装 GitHub
|
||||
管理的插件会替换该托管检出。不允许覆盖安装到本地链接的插件之上;请先
|
||||
unlink 或 uninstall 本地插件。`plugin install` 和 `plugin link` 会创建
|
||||
管理的插件会替换该托管检出。已安装和已链接的插件及其启用状态对当前用户
|
||||
全局生效,可在所有 Herdr 会话中使用。即使 Herdr 服务器没有运行,也可以通过
|
||||
`plugin install` 和 `plugin link` 注册插件。仅安装在 Herdr 0.7.3 命名会话中的
|
||||
插件必须重新 install 或 link;现有的插件配置和状态会保留。
|
||||
不允许覆盖安装到本地链接的插件之上;请先 unlink 或 uninstall 本地插件。
|
||||
`plugin install` 和 `plugin link` 会创建
|
||||
插件的配置和状态目录,`plugin config-dir <id>` 打印配置目录,方便安装
|
||||
文档和 shell 脚本使用。
|
||||
|
||||
|
|
@ -203,6 +210,20 @@ Herdr socket 环境变量。插件作者应在文档中说明所需的系统工
|
|||
`cargo`、`npm`、`bun` 或 `lua`;Herdr 报告构建失败,但不会安装缺失的
|
||||
工具链。
|
||||
|
||||
## 启动钩子
|
||||
|
||||
Herdr 恢复会话且 API socket 就绪后,会为每个已启用插件运行一次
|
||||
`[[startup]]` 命令。实时交接由新服务器接管时会再次运行,但客户端连接、
|
||||
配置重载以及插件 link 或 enable 时不会运行。Herdr 异步启动这些命令,并在
|
||||
普通插件命令日志中记录完成情况。启动钩子失败不会停止服务器。
|
||||
|
||||
启动钩子是一次性初始化命令,不是受监督的守护进程。钩子应恢复插件自己的
|
||||
状态、调用所需的 Herdr API,然后退出。例如,插件可以把声明式 Agent 视图保存到
|
||||
`HERDR_PLUGIN_STATE_DIR`,再由启动钩子读取并重新应用。
|
||||
|
||||
启动钩子会收到普通运行时插件环境和 `HERDR_PLUGIN_EVENT=startup`。安装预览会
|
||||
列出所有启动命令,让用户检查将自动运行的代码。
|
||||
|
||||
## 命令与环境
|
||||
|
||||
运行时命令以插件目录为工作目录执行。Herdr 注入 `HERDR_SOCKET_PATH`、
|
||||
|
|
@ -210,7 +231,8 @@ Herdr socket 环境变量。插件作者应在文档中说明所需的系统工
|
|||
`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、
|
||||
`HERDR_PLUGIN_CONTEXT_JSON`,以及可用时的 `HERDR_WORKSPACE_ID`、
|
||||
`HERDR_TAB_ID` 和 `HERDR_PANE_ID`。动作命令还会收到
|
||||
`HERDR_PLUGIN_ACTION_ID`;事件钩子收到 `HERDR_PLUGIN_EVENT` 和
|
||||
`HERDR_PLUGIN_ACTION_ID`;启动钩子和事件钩子收到 `HERDR_PLUGIN_EVENT`
|
||||
（启动钩子中的值为 `startup`）,事件钩子还会收到
|
||||
`HERDR_PLUGIN_EVENT_JSON`;窗格命令收到 `HERDR_PLUGIN_ENTRYPOINT_ID`。
|
||||
|
||||
`HERDR_PLUGIN_ROOT` 是已安装或已链接的插件目录。不要把用户凭据或持久
|
||||
|
|
|
|||
|
|
@ -297,6 +297,76 @@ Worktree 方法把 Git 检出作为 Herdr 工作区管理。`worktree.create`
|
|||
|
||||
Worktree 命令也发出生命周期事件。`worktree.create` 发出 `workspace.created`、`tab.created`、`pane.created` 和 `worktree.created`。`worktree.open` 发出 `worktree.opened`,并在打开新的 Herdr 工作区时同时发出工作区/标签页/窗格创建事件。`worktree.remove` 发出 `worktree.removed`;如果关联的工作区仍然打开,还会发出 `workspace.closed`。
|
||||
|
||||
## 智能体视图查询
|
||||
|
||||
`agent.view.set` 为内置 Agents 视图设置一个临时的声明式投影。智能体信息或当前
|
||||
UI 上下文变化时,该投影会重新求值。它控制展开和折叠的侧边栏、移动端 Agents
|
||||
列表、鼠标目标、编号聚焦以及上一个/下一个智能体的导航顺序。它不会改变
|
||||
`agent.list`、通知、检测或全局待处理计数。
|
||||
|
||||
下面的示例显示当前呈现的 Space 中的智能体,以及其他位置需要处理的智能体,
|
||||
然后按待处理优先级和最近状态转换排序:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "view_set",
|
||||
"method": "agent.view.set",
|
||||
"params": {
|
||||
"source": "plugin:example.agent-views",
|
||||
"label": "focus",
|
||||
"filter": {
|
||||
"op": "any",
|
||||
"filters": [
|
||||
{
|
||||
"op": "eq",
|
||||
"field": "workspace_id",
|
||||
"value": {"context": "current_workspace_id"}
|
||||
},
|
||||
{
|
||||
"op": "in",
|
||||
"field": "status",
|
||||
"values": ["blocked", "done"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"sort": [
|
||||
{"field": "attention", "order": "desc"},
|
||||
{"field": "state_change_seq", "order": "desc"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
过滤节点的 `op` 可以是 `all`、`any`、`not`、`eq`、`in` 或 `exists`。内置
|
||||
过滤字段是 `status`、`workspace_id`、`tab_id`、`pane_id`、`agent`、`seen`
|
||||
和 `state_change_seq`。要过滤插件上报的窗格元数据,使用 `{"token":"name"}`
|
||||
作为字段。值可以是字符串、布尔值、无符号整数或上下文对象。上下文值包括
|
||||
`current_workspace_id` 和 `current_tab_id`,并且只能与对应的 ID 字段比较。
|
||||
有效 status 值为 `idle`、`working`、`blocked`、`done` 和 `unknown`;`done`
|
||||
表示 idle 且尚未查看。
|
||||
|
||||
排序字段包括 `workspace_order`、`tab_order`、`pane_order`、`attention`、
|
||||
`status`、`agent`、`seen`、`state_change_seq` 或 `{"token":"name"}`。排序是
|
||||
稳定的,按声明顺序求值,并接受 `asc` 或 `desc`。缺失值排在存在值之后。省略
|
||||
`sort` 时,现有 `ui.agent_panel_sort` 策略继续生效。自定义排序会临时替换该
|
||||
策略,但不会重写配置。
|
||||
|
||||
`source` 标识所有者。插件使用 `plugin:<HERDR_PLUGIN_ID>`;当所属插件不存在
|
||||
或被禁用时,Herdr 会拒绝设置。其他调用方可以使用自己的非 `plugin:` source。
|
||||
设置成功会原子替换之前的视图。该视图会持续到被 clear、被替换、所属插件被
|
||||
disable、unlink 或 uninstall,或者服务器退出。需要持久行为的插件应把查询保存到
|
||||
`HERDR_PLUGIN_STATE_DIR`,并从 `[[startup]]` 钩子重新应用。
|
||||
|
||||
可以无条件 clear,也可以只在指定 source 仍拥有视图时 clear:
|
||||
|
||||
```json
|
||||
{"id":"view_clear","method":"agent.view.clear","params":{}}
|
||||
{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}
|
||||
```
|
||||
|
||||
source 不匹配时,活动视图保持不变。set 和 clear 响应使用
|
||||
`type: "agent_view"`,并报告 `active`、`source` 和可选的 `label`。
|
||||
|
||||
## 插件 API
|
||||
|
||||
插件 API 是面向可执行工作流工具的早期宿主面。插件是带 `herdr-plugin.toml` 清单的包。清单声明可分享的动作、事件钩子、终端窗格入口点和链接处理器。动作和窗格仅限清单声明;运行时动作注册和运行时 argv 窗格创建不在 v1 范围内。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
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.
|
||||
|
||||
## Three primitives
|
||||
|
||||
| Primitive | Responsibility |
|
||||
| --- | --- |
|
||||
| Layout (`workspace`, `tab`, and pane topology) | Create and organize terminal locations. |
|
||||
| Pane | Control a raw terminal: run commands, send input, read output, and wait for output. |
|
||||
| Agent | Control a recognized coding agent by name or pane and lifecycle state. |
|
||||
|
||||
A pane exists whether or not it contains an agent. An agent is the recognized process currently running inside a pane. `agent start` therefore requires an existing shell pane and never creates, splits, or moves layout.
|
||||
|
||||
Creating a workspace also creates its first tab and root pane; creating a tab creates its root pane. Use the returned pane ID for the first process, and split only when that layout needs another terminal.
|
||||
|
||||
Creation commands print JSON. Capture IDs from the response instead of predicting them:
|
||||
|
||||
```bash
|
||||
created=$(herdr workspace create --cwd ~/project --label api --no-focus)
|
||||
pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')
|
||||
|
||||
split=$(herdr pane split "$pane_id" --direction right --no-focus)
|
||||
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
||||
```
|
||||
|
||||
`workspace create` returns `.result.workspace`, `.result.tab`, and `.result.root_pane`. `tab create` returns `.result.tab` and `.result.root_pane`. `pane split` returns the new pane as `.result.pane`.
|
||||
|
||||
Moving a pane to another workspace changes its workspace-qualified pane ID. After any `pane move`, continue with `.result.move_result.pane.pane_id`; the response keeps the old value at `.result.move_result.previous_pane_id`. A running process keeps its launch-time Herdr environment, but the old `HERDR_PANE_ID` remains an alias for that terminal, so `--current` stays safe. New commands can still resolve the agent by name after the move, but a wait already in progress ends with `agent_not_running`.
|
||||
|
||||
Use pane commands for shells, tests, servers, CI watchers, and other ordinary terminal processes. Use agent commands when Herdr needs to understand which agent is running or whether it is `working`, `blocked`, `done`, `idle`, or `unknown`.
|
||||
|
||||
## Agent identity and launch
|
||||
|
||||
A pane ID such as `w1:p2` identifies the terminal location. An agent name such as `reviewer` is a convenient alias for the current agent in that pane. Names must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents. The alias is cleared when that agent exits, is released, or is replaced; it does not permanently rename the pane.
|
||||
|
||||
Agent commands accept either a unique live name or the pane ID that currently hosts the agent.
|
||||
|
||||
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.
|
||||
|
||||
`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.
|
||||
|
||||
```bash
|
||||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
```
|
||||
|
||||
Agents launched manually are detected automatically and can be addressed by pane ID. Give one a name when a stable human-readable target is useful:
|
||||
|
||||
```bash
|
||||
herdr agent get w1:p2
|
||||
herdr agent rename w1:p2 reviewer
|
||||
```
|
||||
|
||||
## Choose the control surface
|
||||
|
||||
| Goal | Command |
|
||||
| --- | --- |
|
||||
| Run a shell command and submit it | `pane run` |
|
||||
| Send literal text without Enter | `pane send-text` |
|
||||
| Send terminal keys or modifier chords | `pane send-keys` |
|
||||
| Wait for text or a regular expression | `pane wait-output` |
|
||||
| Start a supported agent in an existing pane | `agent start` |
|
||||
| Submit a prompt, optionally waiting for it | `agent prompt` |
|
||||
| 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.
|
||||
|
||||
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`.
|
||||
|
||||
`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.
|
||||
|
||||
`pane wait-output` does not interpret agent lifecycle. It polls the selected terminal snapshot and searches it immediately, so text that was already present can match. The default source name is `recent`; matching treats that source as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit, and `--regex` uses Rust regular-expression syntax and matches one line at a time.
|
||||
|
||||
At the CLI, both `pane read` and `agent read` print terminal text directly. The default is UTF-8 text with ANSI escapes stripped; use `--format ansi` or `--ansi` to preserve terminal escapes where the source exposes them. The `detection` source is always plain text. For recent sources, `--lines N` selects the last N rendered terminal rows before optional unwrapping; without it, reads default to 80 rows. For `visible` and `detection`, omitting `--lines` returns the full snapshot, while specifying it keeps the last N newline-delimited lines. The socket API returns the text at `.result.read.text`.
|
||||
|
||||
## Known caveat: alternate-screen output
|
||||
|
||||
Full-screen agents such as Claude Code and OpenCode may render in the terminal's alternate screen. Alternate-screen rows do not enter Herdr's host scrollback. If a response exceeds the visible pane, `recent` and `recent-unwrapped` cannot recover rows that the app no longer displays; increasing `--lines` does not make that history available. A larger font or smaller pane makes this more likely.
|
||||
|
||||
Ask the agent for concise responses, enlarge the pane or use a smaller font, or use the agent's own transcript and scrolling controls. After scrolling inside the agent, use `--source visible` to read the page it currently renders.
|
||||
|
||||
Successful `agent start`, `agent prompt`, and `agent wait` commands return the current agent at `.result.agent`. `pane wait-output` returns `.result.pane_id`, `.result.matched_line`, and the matched snapshot at `.result.read`.
|
||||
|
||||
Wait commands have no default timeout and can wait indefinitely. On timeout or another server error, CLI commands print a JSON error to stderr and exit with status 1; invalid CLI syntax exits with status 2.
|
||||
|
||||
## Recipes
|
||||
|
||||
Start a helper, give it work, and wait for that work to settle:
|
||||
|
||||
```bash
|
||||
split=$(herdr pane split --current --direction right --no-focus)
|
||||
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
||||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
|
||||
herdr agent read reviewer --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
Wait for an agent to ask for input, inspect it, and interact with its UI:
|
||||
|
||||
```bash
|
||||
herdr agent wait reviewer --until blocked --timeout 120000
|
||||
herdr agent read reviewer --source recent-unwrapped --lines 80
|
||||
herdr agent send-keys reviewer esc
|
||||
```
|
||||
|
||||
Run an ordinary process and wait for its output without treating it as an agent:
|
||||
|
||||
```bash
|
||||
herdr pane run w1:p3 "just test --watch"
|
||||
herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000
|
||||
```
|
||||
|
||||
See the [CLI reference](/docs/cli-reference/) for the complete command and option list. Shell completions expose the same command tree interactively.
|
||||
|
|
@ -58,7 +58,7 @@ This prevents an agent outside Herdr from trying to control a session it does no
|
|||
|
||||
## Agent-facing reference
|
||||
|
||||
The full command guide lives in the skill file itself. It covers pane IDs, `pane split`, `pane run`, `pane read`, `wait output`, `wait agent-status`, workspace and tab commands, and coordination recipes.
|
||||
The full command guide lives in the skill file itself. It covers pane IDs, `pane split`, `pane run`, `pane read`, `pane wait-output`, `agent wait`, workspace and tab commands, and coordination recipes.
|
||||
|
||||
Read the source file here:
|
||||
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ description: See what Herdr can detect, how agent state works, and how integrati
|
|||
|
||||
Herdr is built for running more than one coding agent at a time. Each agent stays in a real terminal pane with its shell, logs, prompts, and running processes intact. Herdr tracks which panes contain agents, rolls their state up to tabs and workspaces, and lets you jump straight to the pane that needs attention instead of polling every terminal by hand.
|
||||
|
||||
To coordinate agents from scripts or from another agent, see [Agent automation](/docs/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`.
|
||||
|
|
@ -47,7 +49,7 @@ Claude Code, Codex, GitHub Copilot CLI, Droid, Qoder CLI, and Cursor Agent CLI i
|
|||
|
||||
## VMs and sandbox wrappers
|
||||
|
||||
On Linux, wrappers such as VMs, Bubblewrap, or `fence` can hide the real agent process from host `/proc`. Set `HERDR_AGENT=<agent>` on the command, for example `HERDR_AGENT=claude fence -- claude`, to tell Herdr which existing agent screen manifest to use. The hint is scoped to that foreground process; avoid exporting it globally from your shell 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 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.
|
||||
|
||||
## Blocked state
|
||||
|
||||
|
|
@ -110,7 +112,7 @@ herdr agent rename w1:p1 reviewer
|
|||
herdr agent rename reviewer --clear
|
||||
```
|
||||
|
||||
Targets accept terminal IDs, unique agent names, detected or reported agent labels, and legacy pane IDs.
|
||||
Targets accept a unique live agent name or the pane ID that currently hosts the agent. Terminal IDs and bare agent-kind labels are not accepted.
|
||||
|
||||
## Custom status labels
|
||||
|
||||
|
|
@ -131,24 +133,6 @@ herdr pane report-metadata w1:p1 \
|
|||
|
||||
Agent sidebar rows can also opt into `terminal_title` or `terminal_title_stripped`; neither appears in the default rows. The first shows the latest safety-normalized OSC 0/2 terminal title. The second removes one recognized leading activity or spinner glyph and following whitespace. Herdr owns these values on the server; they are ephemeral across a cold restart and remain independent of metadata titles and semantic agent state. Spinner animation can therefore update the raw title without producing a pane update when the stripped text stays the same.
|
||||
|
||||
## Start agents from the CLI
|
||||
|
||||
Use `herdr agent ...` commands when you want a terminal to be treated as an agent target. Agent targets show up in `agent list`, can be read or sent input by agent name, can be waited on by agent state, and can be directly attached.
|
||||
|
||||
Spawn an agent into Herdr from a script:
|
||||
|
||||
```bash
|
||||
herdr agent start reviewer --cwd ~/project --split right -- pi
|
||||
```
|
||||
|
||||
You can place that agent in a specific workspace or tab:
|
||||
|
||||
```bash
|
||||
herdr agent start docs --workspace w1 --tab w1:t1 -- claude
|
||||
```
|
||||
|
||||
Use `herdr pane ...` commands for ordinary terminals, servers, tests, shells, and low-level terminal input. For example, use `pane split` and `pane run` for `cargo test`, not `agent start`, unless that terminal is intentionally being treated as an agent target.
|
||||
|
||||
## Attach directly to an agent
|
||||
|
||||
Attach your current terminal to one agent terminal instead of the full Herdr UI:
|
||||
|
|
|
|||
|
|
@ -130,6 +130,8 @@ 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`.
|
||||
|
||||
## Worktrees
|
||||
|
||||
```bash
|
||||
|
|
@ -154,6 +156,10 @@ 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`.
|
||||
|
||||
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.
|
||||
|
||||
## Panes
|
||||
|
||||
```bash
|
||||
|
|
@ -181,15 +187,19 @@ For pane commands that accept `--current`, Herdr uses the calling pane's
|
|||
`HERDR_PANE_ID` when the command runs inside a Herdr pane. For `pane split`,
|
||||
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`.
|
||||
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:
|
||||
|
||||
```bash
|
||||
herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N]
|
||||
herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
|
||||
herdr pane read <pane_id> --source visible --ansi
|
||||
herdr pane read <pane_id> --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
`pane read` prints UTF-8 terminal text directly. ANSI escapes are stripped by default; use `--format ansi` or `--ansi` to preserve them where the source exposes styling. The `detection` source is always plain text. For recent sources, `--lines N` selects the last N rendered terminal rows before optional unwrapping; without it, reads default to 80 rows. For `visible` and `detection`, omitting `--lines` returns the full snapshot, while specifying it keeps the last N newline-delimited lines. `agent read` uses the same output and line behavior.
|
||||
|
||||
Send input:
|
||||
|
||||
```bash
|
||||
|
|
@ -204,8 +214,9 @@ special keys such as `enter`, `tab`, `esc`, `backspace`, `left`, `right`,
|
|||
and `shift+tab`, function keys such as `f1`, and named punctuation such as
|
||||
`minus`, `plus`, and `backtick`. Legacy `C-c` and `c-c` are accepted as
|
||||
aliases for `ctrl+c`.
|
||||
`esc` is the canonical spelling; `escape` is also accepted.
|
||||
|
||||
`pane run` submits text plus Enter atomically. Prefer it over `send-text` plus `send-keys Enter` for commands.
|
||||
`pane run` honors live bracketed-paste mode and submits text plus Enter atomically. Prefer it over `send-text` plus `send-keys Enter` for commands; the separate send operations remain low-level and non-submitting.
|
||||
|
||||
Report agent state from custom hooks:
|
||||
|
||||
|
|
@ -218,8 +229,23 @@ herdr pane report-agent <pane_id> \
|
|||
[--seq N] \
|
||||
[--agent-session-id ID] \
|
||||
[--agent-session-path PATH]
|
||||
|
||||
herdr pane report-agent-session <pane_id> \
|
||||
--source ID \
|
||||
--agent LABEL \
|
||||
[--seq N] \
|
||||
[--agent-session-id ID] \
|
||||
[--agent-session-path PATH] \
|
||||
[--session-start-source SOURCE]
|
||||
|
||||
herdr pane release-agent <pane_id> \
|
||||
--source ID \
|
||||
--agent LABEL \
|
||||
[--seq N]
|
||||
```
|
||||
|
||||
`report-agent-session` updates native session identity without reporting lifecycle state. `release-agent` ends that source's lifecycle authority when its agent process exits.
|
||||
|
||||
`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.
|
||||
|
|
@ -253,23 +279,34 @@ Metadata text is normalized before storage. Herdr trims surrounding whitespace,
|
|||
|
||||
## Agents
|
||||
|
||||
For the pane-versus-agent model and complete orchestration examples, see [Agent automation](/docs/agent-automation/).
|
||||
|
||||
```bash
|
||||
herdr agent list
|
||||
herdr agent get <target>
|
||||
herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
|
||||
herdr agent send <target> <text>
|
||||
herdr agent send-keys <target> <key> [key ...]
|
||||
herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
|
||||
herdr agent rename <target> <name>|--clear
|
||||
herdr agent focus <target>
|
||||
herdr agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
|
||||
herdr agent wait <target> [--until STATUS]... [--timeout MS]
|
||||
herdr agent attach <target> [--takeover]
|
||||
herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
|
||||
herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
|
||||
herdr agent explain <target> [--json|--verbose]
|
||||
herdr agent explain --file PATH --agent LABEL [--json|--verbose]
|
||||
```
|
||||
|
||||
Agent targets can be terminal IDs, unique agent names, detected or reported agent labels, or legacy pane IDs. Names and labels are agent identities. Terminal IDs and legacy pane IDs are low-level escape hatches.
|
||||
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 read` reads the resolved terminal stream. `agent send` writes literal text to that stream. `agent get`, `agent focus`, `agent wait`, and `agent attach` require the resolved terminal to have agent identity. `agent rename` can assign that identity.
|
||||
`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.
|
||||
|
||||
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.
|
||||
|
||||
`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.
|
||||
|
||||
`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.
|
||||
|
||||
`agent send-keys` sends logical terminal keys such as `enter`, `up`, `esc`, or `ctrl+c`. Herdr validates every key before writing any bytes. `agent read` reads the resolved terminal stream, and `agent rename` names an already detected agent.
|
||||
|
||||
`agent explain` asks the running server to classify the same bottom-buffer detection snapshot used by screen detection, so live output reflects the server's active manifest cache. Because this uses the `agent.explain` socket method, restart or hand off to an updated server after upgrading Herdr before using live explain. Use `--file PATH --agent LABEL` to explain a saved fixture locally instead. The default output shows the agent, final state, manifest source and version, matched rule with its region evidence, and any fallback, skip, or warning reasons. Add `--verbose` for visible evidence flags, cached remote version, local override shadowing, remote update status, and the full evaluated-rules list with matcher and region evidence. Add `--json` for issue reports or tests.
|
||||
|
||||
|
|
@ -299,21 +336,19 @@ 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.
|
||||
|
||||
## Waits
|
||||
## Output waits
|
||||
|
||||
Wait for output in a pane:
|
||||
|
||||
```bash
|
||||
herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]
|
||||
herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]
|
||||
```
|
||||
|
||||
Wait for pane agent state:
|
||||
Use `pane wait-output` for normal commands and servers. Use `agent wait` for coding agents.
|
||||
|
||||
```bash
|
||||
herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]
|
||||
```
|
||||
`pane wait-output` checks the selected snapshot immediately, including output that already exists, then polls until it matches. The default source name is `recent`; matching treats it as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit. `--match` finds a literal substring on one line, and `--regex` uses Rust regular-expression syntax and also matches one line at a time.
|
||||
|
||||
Use `wait output` for normal commands and servers. Use `wait agent-status` for coding agents.
|
||||
`pane wait-output`, `agent wait`, and `agent prompt --wait` wait indefinitely when `--timeout` is omitted. A timeout or server error is emitted as JSON on stderr with exit status 1. CLI usage errors exit with status 2.
|
||||
|
||||
## Integrations
|
||||
|
||||
|
|
@ -365,6 +400,8 @@ herdr plugin disable <plugin_id>
|
|||
|
||||
`plugin install` accepts GitHub shorthand only, such as `ogulcancelik/herdr-plugin-examples/worktree-bootstrap`. It uses `git`, shows a trust preview in interactive terminals, runs supported manifest build commands, and stores GitHub installs in a Herdr-managed directory. Use `--yes` for noninteractive installs. Reinstalling a GitHub-managed plugin replaces that managed checkout. Installing over a locally linked plugin is refused. Plugin manifests must declare `min_herdr_version`; install and link fail when the plugin requires a newer Herdr binary. `plugin list` is human-readable by default; pass `--json` for the raw API response.
|
||||
|
||||
Plugin installation and enabled state are global to the current user. A plugin installed, linked, enabled, or disabled through one Herdr session is immediately available with the same state in every session.
|
||||
|
||||
Local development:
|
||||
|
||||
```bash
|
||||
|
|
@ -431,6 +468,8 @@ in pane or agent APIs. Native non-terminal plugin panes are a later surface.
|
|||
| `recent-unwrapped` | Recent scrollback without soft wrapping. Best for logs. |
|
||||
| `detection` | Bottom-buffer snapshot used by agent screen detection. |
|
||||
|
||||
These meanings apply to reads. For `pane wait-output` only, both `recent` and `recent-unwrapped` search the unwrapped recent snapshot; `recent` remains the default spelling.
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|
|
|
|||
|
|
@ -299,6 +299,18 @@ Space rows accept these built-in tokens:
|
|||
|
||||
Tokens render in their configured order. Herdr normally separates adjacent values with ` · ` and uses a single space after `state_icon`. Missing values and their separators disappear; a row disappears when none of its tokens have a value. Each layout may contain at most 16 rows, with at most 16 tokens in each row.
|
||||
|
||||
A token entry can also be an inline style table:
|
||||
|
||||
```toml
|
||||
[ui.sidebar.agents]
|
||||
rows = [
|
||||
["state_icon", { token = "workspace", bold = false }, "tab"],
|
||||
[{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }],
|
||||
]
|
||||
```
|
||||
|
||||
`fg` accepts strict `#RGB` or `#RRGGBB`. `bold` and `dim` accept booleans. Omitted fields preserve the token's contextual style; explicit `false` removes that modifier. Styling applies to one occurrence, so the same token may look different in another row or agent override. A foreground override replaces all semantic foregrounds inside that occurrence: for example, styled `git_status` ahead and behind counts use one color instead of their default green and red. Token styles never change separators or row backgrounds.
|
||||
|
||||
`row_gap` controls the blank terminal rows between entries, independently for the Agent and Space panels. It defaults to `0`, which packs entries together; set it to `1` to restore the previous spacing. It does not add spacing between the content lines declared in `rows`. Consecutive indented worktree children remain packed as one Space group.
|
||||
|
||||
Override the complete Agent layout for a known agent under `rows_by_agent`:
|
||||
|
|
@ -338,7 +350,9 @@ 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. Metadata reporters provide values only; they cannot choose rows or styling. See [CLI reference: report metadata](/docs/cli-reference/#panes) for clearing, sequencing, and expiring values.
|
||||
Use `herdr workspace report-metadata` in the same way for custom Space tokens. Unreported custom tokens simply 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.
|
||||
|
||||
Sidebar row settings affect only the expanded desktop sidebar. Collapsed and mobile views keep their compact layouts.
|
||||
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ Herdr writes the bundled extension to:
|
|||
~/.pi/agent/extensions/herdr-agent-state.ts
|
||||
```
|
||||
|
||||
If `PI_CODING_AGENT_DIR` is set, Herdr writes to `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts` instead. The extensions directory must already exist. Uninstall removes only that extension file.
|
||||
If `PI_CODING_AGENT_DIR` is set, Herdr writes to `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts` instead. Herdr creates the extensions directory when the Pi agent directory already exists. Uninstall removes only that extension file.
|
||||
|
||||
## OMP
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ Herdr writes the bundled extension to:
|
|||
~/.omp/agent/extensions/herdr-omp-agent-state.ts
|
||||
```
|
||||
|
||||
If `PI_CODING_AGENT_DIR` is set, Herdr writes to `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts` instead. The extensions directory must already exist. Uninstall removes only that extension file.
|
||||
If `PI_CODING_AGENT_DIR` is set, Herdr writes to `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts` instead. Herdr creates the extensions directory when the OMP agent directory already exists. Uninstall removes only that extension file.
|
||||
|
||||
The OMP integration reports `omp` as the agent label, lifecycle state, and native session identity through Herdr's socket API. It does not require native process detection for the `omp` executable, and Herdr can resume an OMP pane with `omp --resume=<session>` after a server restart.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
title: エージェント自動化
|
||||
description: Herdr のレイアウト、ペイン、エージェントの各プリミティブを使い、スクリプトや別のエージェントからコーディングエージェントを連携させます。
|
||||
---
|
||||
|
||||
Herdr はコーディングエージェントの自動化レイヤーとして使えます。スクリプトから制御することも、ひとつのエージェントから別のエージェントへ作業を渡し、状態を確認して結果を集めることもできます。重要なのは、目的に合うプリミティブを選ぶことです。
|
||||
|
||||
## 3 つのプリミティブ
|
||||
|
||||
| プリミティブ | 責務 |
|
||||
| --- | --- |
|
||||
| レイアウト（`workspace`、`tab`、ペイン構成） | ターミナルの場所を作成し、整理する。 |
|
||||
| ペイン | 生のターミナルを制御する。コマンド実行、入力送信、出力読み取り、出力待機を行う。 |
|
||||
| エージェント | 認識済みコーディングエージェントを、名前またはペインとライフサイクル状態に基づいて制御する。 |
|
||||
|
||||
ペインは、エージェントが入っていなくても存在します。エージェントは、ペイン内で現在実行されていると Herdr が認識したプロセスです。そのため `agent start` には既存のシェルペインが必要で、レイアウトの作成、分割、移動は行いません。
|
||||
|
||||
ワークスペースを作成すると最初のタブとルートペインも作られ、タブを作成するとそのルートペインも作られます。最初のプロセスには返されたペイン ID を使い、そのレイアウトに別のターミナルが必要なときだけ分割します。
|
||||
|
||||
作成コマンドは JSON を出力します。ID を推測せず、レスポンスから取得してください:
|
||||
|
||||
```bash
|
||||
created=$(herdr workspace create --cwd ~/project --label api --no-focus)
|
||||
pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')
|
||||
|
||||
split=$(herdr pane split "$pane_id" --direction right --no-focus)
|
||||
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
||||
```
|
||||
|
||||
`workspace create` は `.result.workspace`、`.result.tab`、`.result.root_pane` を返します。`tab create` は `.result.tab` と `.result.root_pane` を返し、`pane split` は新しいペインを `.result.pane` として返します。
|
||||
|
||||
ペインを別のワークスペースへ移動すると、ワークスペース修飾付きのペイン ID が変わります。`pane move` の後は `.result.move_result.pane.pane_id` を使い、以前の値が必要なら `.result.move_result.previous_pane_id` を参照してください。実行中プロセスは起動時の Herdr 環境を保ちますが、以前の `HERDR_PANE_ID` はそのターミナルの別名として残るため、`--current` は引き続き安全に使えます。移動後に始めるコマンドはエージェント名で解決できますが、すでに進行中の待機は `agent_not_running` で終了します。
|
||||
|
||||
シェル、テスト、サーバー、CI ウォッチャーなどの通常のターミナルプロセスにはペインコマンドを使います。どのエージェントが動いているか、または状態が `working`、`blocked`、`done`、`idle`、`unknown` のどれかを Herdr に判断させる場合はエージェントコマンドを使います。
|
||||
|
||||
## エージェントの識別子と起動
|
||||
|
||||
`w1:p2` のようなペイン ID はターミナルの場所を識別します。`reviewer` のようなエージェント名は、そのペインに現在いるエージェントの扱いやすい別名です。名前は `[a-z][a-z0-9_-]{0,31}` に一致し、ライブエージェント間で一意でなければなりません。エージェントが終了、解放、または置換されると別名は消えます。ペイン自体の恒久的な名前ではありません。
|
||||
|
||||
エージェントコマンドは、一意なライブ名、または現在そのエージェントをホストしているペイン 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` です。`--` より後の引数は、その実行ファイルへそのまま渡されます。
|
||||
|
||||
`agent start` は、同じターミナルで期待したエージェントを検出し、対話入力の準備ができたと Herdr が判断してから返ります。起動待機はデフォルトで 30 秒です。`--timeout` は 3000 より大きく 300000 以下のミリ秒で指定します。
|
||||
|
||||
```bash
|
||||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
```
|
||||
|
||||
手動で起動したエージェントも自動検出され、ペイン ID で指定できます。人が読みやすい安定した対象名が必要なら名前を付けます:
|
||||
|
||||
```bash
|
||||
herdr agent get w1:p2
|
||||
herdr agent rename w1:p2 reviewer
|
||||
```
|
||||
|
||||
## 操作面を選ぶ
|
||||
|
||||
| 目的 | コマンド |
|
||||
| --- | --- |
|
||||
| シェルコマンドを実行して送信する | `pane run` |
|
||||
| Enter を付けずに文字列を送る | `pane send-text` |
|
||||
| ターミナルキーや修飾キーの組み合わせを送る | `pane send-keys` |
|
||||
| 文字列や正規表現を待つ | `pane wait-output` |
|
||||
| 既存のペインで対応済みエージェントを起動する | `agent start` |
|
||||
| プロンプトを送信し、必要なら完了を待つ | `agent prompt` |
|
||||
| エージェントの対話 UI にキーを送る | `agent send-keys` |
|
||||
| エージェントのライフサイクル状態を待つ | `agent wait` |
|
||||
|
||||
`agent prompt` は文字列とエンコード済み Enter を送信し、ターミナルの現在の bracketed paste モードを尊重します。working 中のエージェントにも送信できます。`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` が必要です。
|
||||
|
||||
`idle` は、エージェントが入力待ちで、そのタブがフォーカス中の Herdr UI ですでに表示済みであることを示します。`done` は同じ基礎的な idle 状態ですが、バックグラウンド作業が完了してから、そのタブをフォーカスするか `pane focus` / `agent focus` で対象にするまで使われます。CLI で読み取るだけでは表示済みになりません。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するもののライフサイクルを確実に分類できない状態で、成功完了を意味しません。違いが重要なら正確な `--until` を指定してください。
|
||||
|
||||
`pane wait-output` はエージェントのライフサイクルを解釈しません。選択したターミナルスナップショットをポーリングし、最初にすぐ検索するため、すでに存在する文字列も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更でき、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。
|
||||
|
||||
CLI では、`pane read` と `agent read` のどちらもターミナルテキストを直接出力します。デフォルトは ANSI エスケープを除去した UTF-8 テキストです。ソースに装飾が含まれる場合、`--format ansi` または `--ansi` でエスケープを残します。`detection` ソースは常にプレーンテキストです。recent 系ソースでは、`--lines N` は折り返し解除の前に末尾の N 描画行を選び、省略時は 80 行です。`visible` と `detection` では、省略時にスナップショット全体を返し、指定時は改行で区切られた末尾 N 行を返します。socket API ではテキストを `.result.read.text` に返します。
|
||||
|
||||
## 既知の注意点: 代替画面の出力
|
||||
|
||||
Claude Code や OpenCode などの全画面エージェントは、ターミナルの代替画面に描画することがあります。代替画面の行は Herdr のホスト側スクロールバックには入りません。応答が表示中のペインを超えると、アプリが表示しなくなった行を `recent` や `recent-unwrapped` で復元することはできません。`--lines` を増やしても、その履歴は取得できません。フォントが大きい場合やペインが小さい場合は、より起こりやすくなります。
|
||||
|
||||
エージェントに簡潔な応答を求めるか、ペインを広げる、フォントを小さくする、またはエージェント自身のトランスクリプトやスクロール操作を使ってください。エージェント内でスクロールした後、`--source visible` を使うと、現在描画されているページを読み取れます。
|
||||
|
||||
成功した `agent start`、`agent prompt`、`agent wait` は現在のエージェントを `.result.agent` に返します。`pane wait-output` は `.result.pane_id`、`.result.matched_line`、一致したスナップショット `.result.read` を返します。
|
||||
|
||||
wait コマンドにはデフォルトのタイムアウトがなく、無期限に待機できます。タイムアウトやサーバーエラーでは JSON エラーを stderr に出して終了コード 1、CLI 構文エラーでは終了コード 2 を返します。
|
||||
|
||||
## レシピ
|
||||
|
||||
補助エージェントを起動して作業を渡し、その作業が落ち着くまで待ちます:
|
||||
|
||||
```bash
|
||||
split=$(herdr pane split --current --direction right --no-focus)
|
||||
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
||||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
|
||||
herdr agent read reviewer --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
エージェントが入力を求めるまで待ち、内容を確認して対話 UI を操作します:
|
||||
|
||||
```bash
|
||||
herdr agent wait reviewer --until blocked --timeout 120000
|
||||
herdr agent read reviewer --source recent-unwrapped --lines 80
|
||||
herdr agent send-keys reviewer esc
|
||||
```
|
||||
|
||||
通常のプロセスを実行し、エージェントとして扱わずに出力を待ちます:
|
||||
|
||||
```bash
|
||||
herdr pane run w1:p3 "just test --watch"
|
||||
herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000
|
||||
```
|
||||
|
||||
コマンドとオプションの完全な一覧は [CLI リファレンス](/ja/docs/cli-reference/) を参照してください。シェル補完でも同じコマンドツリーを対話的に確認できます。
|
||||
|
|
@ -58,7 +58,7 @@ claude
|
|||
|
||||
## エージェント向けリファレンス
|
||||
|
||||
コマンドの完全なガイドはスキルファイル自体にあります。ペイン ID、`pane split`、`pane run`、`pane read`、`wait output`、`wait agent-status`、ワークスペースとタブのコマンド、協調動作のレシピを扱っています。
|
||||
コマンドの完全なガイドはスキルファイル自体にあります。ペイン ID、`pane split`、`pane run`、`pane read`、`pane wait-output`、`agent wait`、ワークスペースとタブのコマンド、協調動作のレシピを扱っています。
|
||||
|
||||
ソースファイルはこちら:
|
||||
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ description: Herdr が何を検出できるか、エージェント状態の仕
|
|||
|
||||
Herdr は複数のコーディングエージェントを同時に動かすために作られています。各エージェントは、シェル、ログ、プロンプト、実行中プロセスをそのまま保った実際のターミナルペインの中にいます。Herdr はどのペインにエージェントがいるかを追跡し、その状態をタブとワークスペースに集約し、すべてのターミナルを手作業で見回る代わりに、注意が必要なペインへ直接ジャンプできるようにします。
|
||||
|
||||
スクリプトや別のエージェントから連携させる方法は、[エージェント自動化](/ja/docs/agent-automation/) を参照してください。
|
||||
|
||||
## 対応エージェント
|
||||
|
||||
一般的なコーディングエージェントは、追加設定なしで自動検出されます。重要な違いは Herdr がエージェントを見えるかどうかではありません。どのシグナルが `idle`、`working`、`blocked` を決定する権限を持つかです。
|
||||
|
|
@ -47,7 +49,7 @@ Claude Code、Codex、GitHub Copilot CLI、Droid、Qoder CLI、Cursor Agent CLI
|
|||
|
||||
## VM とサンドボックスラッパー
|
||||
|
||||
Linux では、VM、Bubblewrap、`fence` のようなラッパーがホストの `/proc` から実際のエージェントプロセスを隠すことがあります。コマンドに `HERDR_AGENT=<agent>` を設定して (例: `HERDR_AGENT=claude fence -- claude`)、どの既存エージェントのスクリーンマニフェストを使うべきか Herdr に伝えてください。このヒントはそのフォアグラウンドプロセスにスコープされます。継承されるすべてのフォアグラウンドプロセスをそのエージェントとして扱いたいのでない限り、シェルからグローバルに export するのは避けてください。
|
||||
Linux と macOS では、ホストから見えるラッパーが実際のエージェントプロセスを Herdr から隠すことがあります。ラッパーのコマンドに `HERDR_AGENT=<agent>` を設定して、どの既存エージェントのスクリーンマニフェストを使うべきか Herdr に伝えてください。たとえば、Linux では `HERDR_AGENT=claude fence -- claude`、macOS では `HERDR_AGENT=claude nono run --profile claude-code -- claude` を実行します。このヒントはそのフォアグラウンドプロセスにスコープされます。VM やコンテナの内部だけで設定しても Herdr からは見えません。また、継承されるすべてのフォアグラウンドプロセスをそのエージェントとして扱いたいのでない限り、グローバルな export は避けてください。
|
||||
|
||||
## blocked 状態
|
||||
|
||||
|
|
@ -110,7 +112,7 @@ herdr agent rename w1:p1 reviewer
|
|||
herdr agent rename reviewer --clear
|
||||
```
|
||||
|
||||
ターゲットにはターミナル ID、一意なエージェント名、検出または報告されたエージェントラベル、レガシーなペイン ID が使えます。
|
||||
ターゲットには一意なライブエージェント名、または現在そのエージェントをホストしているペイン ID を使います。ターミナル ID とエージェント kind のラベルだけでは指定できません。
|
||||
|
||||
## カスタムステータスラベル
|
||||
|
||||
|
|
@ -131,24 +133,6 @@ herdr pane report-metadata w1:p1 \
|
|||
|
||||
エージェントサイドバー行では、`terminal_title` または `terminal_title_stripped` も任意で使えます。どちらもデフォルト行には含まれません。前者は安全性のために正規化された最新の OSC 0/2 ターミナルタイトルを表示し、後者は先頭にある認識済みのアクティビティまたはスピナーのグリフ 1 つと、それに続く空白を除去します。これらの値は Herdr サーバーが所有し、コールドリスタートをまたいで保持されません。また、メタデータのタイトルや意味的なエージェント状態から独立しています。そのため、除去後のテキストが同じなら、スピナーのアニメーションで生のタイトルが変わってもペイン更新は発行されません。
|
||||
|
||||
## CLI からエージェントを起動する
|
||||
|
||||
ターミナルをエージェントターゲットとして扱いたいときは `herdr agent ...` コマンドを使います。エージェントターゲットは `agent list` に表示され、エージェント名で読み取りや入力送信ができ、エージェント状態で wait でき、直接アタッチできます。
|
||||
|
||||
スクリプトから Herdr にエージェントを起動します:
|
||||
|
||||
```bash
|
||||
herdr agent start reviewer --cwd ~/project --split right -- pi
|
||||
```
|
||||
|
||||
特定のワークスペースやタブに配置することもできます:
|
||||
|
||||
```bash
|
||||
herdr agent start docs --workspace w1 --tab w1:t1 -- claude
|
||||
```
|
||||
|
||||
通常のターミナル、サーバー、テスト、シェル、低レベルなターミナル入力には `herdr pane ...` コマンドを使ってください。たとえば `cargo test` には `agent start` ではなく `pane split` と `pane run` を使います。そのターミナルを意図的にエージェントターゲットとして扱うのでない限り。
|
||||
|
||||
## エージェントに直接アタッチする
|
||||
|
||||
完全な Herdr UI ではなく、ひとつのエージェントターミナルに現在のターミナルをアタッチします:
|
||||
|
|
|
|||
|
|
@ -126,6 +126,8 @@ herdr workspace close <workspace_id>
|
|||
herdr workspace create --cwd ~/project --label api --no-focus
|
||||
```
|
||||
|
||||
ワークスペースは最上位のプロジェクトまたは作業コンテキストです。作成時に最初のタブとルートペインも作られます。JSON レスポンスの `.result.workspace.workspace_id`、`.result.tab.tab_id`、`.result.root_pane.pane_id` から各 ID を取得できます。
|
||||
|
||||
## Worktree
|
||||
|
||||
```bash
|
||||
|
|
@ -150,6 +152,10 @@ herdr tab rename <tab_id> <label>
|
|||
herdr tab close <tab_id>
|
||||
```
|
||||
|
||||
タブはワークスペース内の別のターミナルレイアウトです。`--workspace` を省略すると、`tab create` はアクティブなワークスペースを使い、存在しなければ失敗します。JSON レスポンスの `.result.tab.tab_id` と `.result.root_pane.pane_id` から ID を取得できます。
|
||||
|
||||
ワークスペースとタブの作成、およびペインの分割は、デフォルトではフォーカスを変えません。`--focus` は新しいレイアウトを選択し、`--no-focus` はデフォルトを明示します。`--cwd` がない場合、新しいターミナルは `terminal.new_cwd` の設定に従い、デフォルトでは元のペインまたはワークスペースを引き継ぎます。各 `--env KEY=VALUE` は新しいルートシェルの環境変数を追加または置換します。
|
||||
|
||||
## ペイン
|
||||
|
||||
```bash
|
||||
|
|
@ -173,14 +179,20 @@ herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--f
|
|||
herdr pane close <pane_id>
|
||||
```
|
||||
|
||||
`--current` を受け付けるペインコマンドは、Herdr ペイン内から実行した場合、呼び出し元の `HERDR_PANE_ID` を使います。`pane split` では、明示したペイン ID または `--pane ID` がそのペインを、`--current` が呼び出し元ペインを分割します。対象を省略すると UI でフォーカス中のペインを使います。分割レスポンスでは、新しいペイン ID は `.result.pane.pane_id` にあります。
|
||||
|
||||
`pane move` の後続コマンドには `.result.move_result.pane.pane_id` を使います。別ワークスペースへの移動ではワークスペース修飾付きのペイン ID が変わり、以前の値は `.result.move_result.previous_pane_id` に残ります。実行中プロセスの `HERDR_PANE_ID`、`HERDR_TAB_ID`、`HERDR_WORKSPACE_ID` は起動時の値のままですが、Herdr は以前のペイン ID をそのターミナルの別名として保持するため、`--current` を使うペインコマンドは引き続き解決できます。ライブエージェント名もターミナルに追従します。
|
||||
|
||||
出力を読む:
|
||||
|
||||
```bash
|
||||
herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N]
|
||||
herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
|
||||
herdr pane read <pane_id> --source visible --ansi
|
||||
herdr pane read <pane_id> --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
`pane read` は UTF-8 のターミナルテキストを直接出力します。デフォルトでは ANSI エスケープを除去し、ソースに装飾が含まれる場合は `--format ansi` または `--ansi` で保持します。`detection` ソースは常にプレーンテキストです。recent 系ソースでは、`--lines N` は折り返し解除の前に末尾の N 描画行を選び、省略時は 80 行です。`visible` と `detection` では、省略時にスナップショット全体を返し、指定時は改行で区切られた末尾 N 行を返します。`agent read` も同じ出力と行数の動作です。
|
||||
|
||||
入力を送る:
|
||||
|
||||
```bash
|
||||
|
|
@ -191,7 +203,9 @@ herdr pane run <pane_id> <command>
|
|||
|
||||
`<key>` は Herdr のキーコンボ構文を使います: `a` のような通常の印字可能キー、`enter`、`tab`、`esc`、`backspace`、`left`、`right`、`up`、`down` のような特殊キー、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` のような修飾キーコード、`f1` のようなファンクションキー、そして `minus`、`plus`、`backtick` のような名前付き記号です。レガシーな `C-c` と `c-c` は `ctrl+c` のエイリアスとして受け付けられます。
|
||||
|
||||
`pane run` はテキストと Enter をアトミックに送信します。コマンドには `send-text` + `send-keys Enter` よりこちらを使ってください。
|
||||
標準表記は `esc` ですが、`escape` も使えます。
|
||||
|
||||
`pane run` は現在の bracketed paste モードを尊重し、テキストと Enter をアトミックに送信します。コマンドには `send-text` + `send-keys Enter` よりこちらを使ってください。個別の送信操作は低レベルのままで、コマンドを送信しません。
|
||||
|
||||
カスタムフックからエージェント状態を報告する:
|
||||
|
||||
|
|
@ -204,8 +218,23 @@ herdr pane report-agent <pane_id> \
|
|||
[--seq N] \
|
||||
[--agent-session-id ID] \
|
||||
[--agent-session-path PATH]
|
||||
|
||||
herdr pane report-agent-session <pane_id> \
|
||||
--source ID \
|
||||
--agent LABEL \
|
||||
[--seq N] \
|
||||
[--agent-session-id ID] \
|
||||
[--agent-session-path PATH] \
|
||||
[--session-start-source SOURCE]
|
||||
|
||||
herdr pane release-agent <pane_id> \
|
||||
--source ID \
|
||||
--agent LABEL \
|
||||
[--seq N]
|
||||
```
|
||||
|
||||
`report-agent-session` はライフサイクル状態を報告せずにネイティブセッション識別子を更新します。`release-agent` は、そのエージェントプロセスが終了したときに、そのソースのライフサイクル権限を終了します。
|
||||
|
||||
公式インテグレーションがネイティブセッション参照を報告している場合、`pane get`、`pane list`、`agent get`、`agent list` は読み取り専用の `agent_session` オブジェクトを含みます。ネイティブセッション参照が保存されていない場合、このフィールドは省略されます。
|
||||
|
||||
これらのコマンドは、ペインを制御しているフォアグラウンドプロセスの cwd を解決できる場合に `foreground_cwd` を含みます。既存の `cwd` フィールドは、ラベルと follow-cwd 挙動に使われるペイン/ワークスペースの cwd のままです。
|
||||
|
|
@ -237,23 +266,34 @@ herdr pane report-metadata <pane_id> \
|
|||
|
||||
## エージェント
|
||||
|
||||
ペインとエージェントの使い分けや一連の連携例は、[エージェント自動化](/ja/docs/agent-automation/) を参照してください。
|
||||
|
||||
```bash
|
||||
herdr agent list
|
||||
herdr agent get <target>
|
||||
herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
|
||||
herdr agent send <target> <text>
|
||||
herdr agent send-keys <target> <key> [key ...]
|
||||
herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
|
||||
herdr agent rename <target> <name>|--clear
|
||||
herdr agent focus <target>
|
||||
herdr agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
|
||||
herdr agent wait <target> [--until STATUS]... [--timeout MS]
|
||||
herdr agent attach <target> [--takeover]
|
||||
herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
|
||||
herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
|
||||
herdr agent explain <target> [--json|--verbose]
|
||||
herdr agent explain --file PATH --agent LABEL [--json|--verbose]
|
||||
```
|
||||
|
||||
エージェントターゲットには、ターミナル ID、一意なエージェント名、検出または報告されたエージェントラベル、レガシーなペイン ID が使えます。名前とラベルはエージェントのアイデンティティです。ターミナル ID とレガシーペイン ID は低レベルな逃げ道です。
|
||||
エージェントターゲットは、一意なライブエージェント名、または現在そのエージェントをホストしているペイン ID です。ターミナル ID とエージェント kind のラベルだけでは指定できません。`agent start` で起動するエージェントには名前が必須で、手動で起動したエージェントは名前なしのままペイン ID で指定します。
|
||||
|
||||
`agent read` は解決されたターミナルストリームを読みます。`agent send` はそのストリームにリテラルのテキストを書き込みます。`agent get`、`agent focus`、`agent wait`、`agent attach` は、解決されたターミナルがエージェントのアイデンティティを持つことを要求します。`agent rename` はそのアイデンティティを割り当てられます。
|
||||
`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、置換で消えます。一時的に検出できないだけでは消えません。
|
||||
|
||||
start は、期待したエージェントが同じターミナルを所有し、対話入力の準備ができてから返ります。デフォルトの起動タイムアウトは 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` です。
|
||||
|
||||
`idle` は入力待ちで、そのタブがフォーカス中の Herdr UI ですでに表示済みの状態です。`done` は同じ基礎的な idle 状態ですが、表示していないバックグラウンド作業が完了したときに使われます。そのタブをフォーカスするか `pane focus` / `agent focus` で対象にすると表示済みになりますが、CLI で読み取るだけでは変わりません。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するものの確実に分類できない状態で、作業の成功を意味しません。
|
||||
|
||||
`agent send-keys` は `enter`、`up`、`esc`、`ctrl+c` などの論理キーを送ります。Herdr は 1 バイトも書き込む前に全キーを検証します。`agent read` は解決されたターミナルストリームを読み、`agent rename` は検出済みエージェントに名前を付けます。
|
||||
|
||||
`agent explain` は、スクリーン検出が使うのと同じ下部バッファの検出スナップショットの分類を実行中のサーバーに依頼します。そのためライブの出力はサーバーのアクティブなマニフェストキャッシュを反映します。これは `agent.explain` ソケットメソッドを使うので、Herdr のアップグレード後にライブ explain を使う前に、サーバーを再起動するか更新済みサーバーへハンドオフしてください。保存済みフィクスチャをローカルで説明するには `--file PATH --agent LABEL` を使います。デフォルトの出力には、エージェント、最終状態、マニフェストのソースとバージョン、リージョンの証拠付きでマッチしたルール、そしてフォールバック・スキップ・警告の理由が表示されます。`--verbose` を付けると、可視の証拠フラグ、キャッシュされたリモートバージョン、ローカルオーバーライドのシャドーイング、リモート更新状況、マッチャーとリージョンの証拠付きの評価済みルール全リストが表示されます。issue の報告やテストには `--json` を付けてください。
|
||||
|
||||
|
|
@ -270,21 +310,19 @@ herdr terminal title clear
|
|||
ダイレクトアタッチからは `ctrl+b q` でデタッチします。リテラルの `ctrl+b` は `ctrl+b ctrl+b` で送ります。
|
||||
`terminal title clear` は Herdr のデフォルトの外側ターミナルウィンドウタイトルを復元します。
|
||||
|
||||
## Wait
|
||||
## 出力待機
|
||||
|
||||
ペインの出力を待つ:
|
||||
|
||||
```bash
|
||||
herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]
|
||||
herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]
|
||||
```
|
||||
|
||||
ペインのエージェント状態を待つ:
|
||||
通常のコマンドやサーバーには `pane wait-output` を使います。コーディングエージェントには `agent wait` を使います。
|
||||
|
||||
```bash
|
||||
herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]
|
||||
```
|
||||
`pane wait-output` は選択したスナップショットを最初にすぐ検索するため、すでに存在する出力も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更できます。`--match` は 1 行内のリテラル部分文字列を検索し、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。
|
||||
|
||||
通常のコマンドやサーバーには `wait output` を使います。コーディングエージェントには `wait agent-status` を使います。
|
||||
`pane wait-output`、`agent wait`、`agent prompt --wait` は、`--timeout` を省略すると無期限に待ちます。タイムアウトまたはサーバーエラーは JSON として stderr に出力され、終了コード 1 になります。CLI 使用法のエラーは終了コード 2 です。
|
||||
|
||||
## インテグレーション
|
||||
|
||||
|
|
@ -389,6 +427,8 @@ herdr plugin pane close <pane_id>
|
|||
| `recent-unwrapped` | ソフト折り返しなしの直近のスクロールバック。ログに最適。 |
|
||||
| `detection` | エージェントのスクリーン検出が使う下部バッファのスナップショット。 |
|
||||
|
||||
この表は読み取り時の意味です。`pane wait-output` に限り、`recent` と `recent-unwrapped` はどちらも recent の折り返し前スナップショットを検索し、デフォルト表記は `recent` です。
|
||||
|
||||
## 環境変数
|
||||
|
||||
| 変数 | 目的 |
|
||||
|
|
|
|||
|
|
@ -295,6 +295,18 @@ Space の行では、次の組み込みトークンを使えます:
|
|||
|
||||
トークンは設定された順序で描画されます。Herdr は通常、隣接する値を ` · ` で区切り、`state_icon` の後には空白を 1 つ入れます。値がない場合、その値と区切りは表示されません。すべてのトークンに値がない行は表示されません。各レイアウトは最大 16 行、各行は最大 16 トークンです。
|
||||
|
||||
トークンエントリにはインラインのスタイルテーブルも使えます:
|
||||
|
||||
```toml
|
||||
[ui.sidebar.agents]
|
||||
rows = [
|
||||
["state_icon", { token = "workspace", bold = false }, "tab"],
|
||||
[{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }],
|
||||
]
|
||||
```
|
||||
|
||||
`fg` は厳密な `#RGB` または `#RRGGBB`、`bold` と `dim` は真偽値です。省略したフィールドはコンテキストのスタイルを保持し、明示的な `false` はその修飾を解除します。スタイルは 1 つの出現箇所だけに適用されます。`fg` を指定した `git_status` では、既定の緑/赤ではなく ahead と behind の両方が同じ色になります。区切りと行の背景は変更されません。
|
||||
|
||||
`row_gap` は、Agent パネルと Space パネルごとに、エントリ間の空白行数を指定します。デフォルトは `0` で、エントリを詰めて表示します。以前の間隔に戻すには `1` に設定します。`rows` で定義したコンテンツ行の間隔には影響しません。連続するインデントされた worktree の子は、1 つの Space グループとして詰めて表示されます。
|
||||
|
||||
既知のエージェントについて Agent の完全なレイアウトを上書きするには、`rows_by_agent` を使います:
|
||||
|
|
@ -334,7 +346,9 @@ herdr pane report-metadata <pane_id> \
|
|||
--token summary="reviewing authentication"
|
||||
```
|
||||
|
||||
カスタム Space トークンには、同じ方法で `herdr workspace report-metadata` を使います。報告されていないカスタムトークンは表示されません。メタデータの報告元が提供できるのは値だけで、行やスタイルは選べません。値のクリア、シーケンス、有効期限については、[CLI リファレンス: report metadata](/docs/cli-reference/#panes)を参照してください。
|
||||
カスタム Space トークンには、同じ方法で `herdr workspace report-metadata` を使います。報告されていないカスタムトークンは表示されません。
|
||||
|
||||
メタデータの報告元が提供できるのは値だけで、スタイルはローカルのサイドバー設定で管理します。上限、クリア、シーケンス、有効期限については、[CLI リファレンス: report metadata](/docs/cli-reference/#panes)を参照してください。
|
||||
|
||||
サイドバーの行設定は、展開されたデスクトップサイドバーにだけ適用されます。折りたたみ表示とモバイル表示はコンパクトなレイアウトを保ちます。
|
||||
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ Herdr はバンドルされた拡張を次の場所に書き込みます:
|
|||
~/.pi/agent/extensions/herdr-agent-state.ts
|
||||
```
|
||||
|
||||
`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts` に書き込みます。extensions ディレクトリはあらかじめ存在している必要があります。アンインストールはその拡張ファイルだけを削除します。
|
||||
`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts` に書き込みます。Pi の agent ディレクトリが存在する場合、Herdr は extensions ディレクトリを作成します。アンインストールはその拡張ファイルだけを削除します。
|
||||
|
||||
## OMP
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ Herdr はバンドルされた拡張を次の場所に書き込みます:
|
|||
~/.omp/agent/extensions/herdr-omp-agent-state.ts
|
||||
```
|
||||
|
||||
`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts` に書き込みます。extensions ディレクトリはあらかじめ存在している必要があります。アンインストールはその拡張ファイルだけを削除します。
|
||||
`PI_CODING_AGENT_DIR` が設定されている場合は、代わりに `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts` に書き込みます。OMP の agent ディレクトリが存在する場合、Herdr は extensions ディレクトリを作成します。アンインストールはその拡張ファイルだけを削除します。
|
||||
|
||||
OMP インテグレーションは、Herdr のソケット API を通じてエージェントラベル `omp`、ライフサイクル状態、ネイティブセッション識別を報告します。`omp` 実行ファイルのネイティブプロセス検出は不要で、Herdr はサーバー再起動後に `omp --resume=<session>` で OMP ペインを resume できます。
|
||||
|
||||
|
|
|
|||
|
|
@ -74,6 +74,9 @@ command = ["npm", "ci"]
|
|||
command = ["npm", "run", "build"]
|
||||
platforms = ["linux", "macos"]
|
||||
|
||||
[[startup]]
|
||||
command = ["node", "dist/restore.js"]
|
||||
|
||||
[[actions]]
|
||||
id = "apply"
|
||||
title = "Apply layout"
|
||||
|
|
@ -110,10 +113,10 @@ ASCII の英字、数字、コロン、アンダースコア、ハイフンが
|
|||
一意な名前が必要なとき、Herdr はアクション id を `plugin.id.action` の形に修飾します。
|
||||
|
||||
プラグインが動作する場所は `platforms = ["linux", "macos", "windows"]` で宣言します。
|
||||
ビルドコマンド、アクション、イベントフック、ペイン、リンクハンドラーも独自の
|
||||
`platforms` を宣言でき、項目レベルの platforms はトップレベルのリストを
|
||||
上書きします。トップレベルの `platforms` がないローカルプラグインは警告付きで
|
||||
リンクされます。
|
||||
ビルドコマンド、スタートアップフック、アクション、イベントフック、ペイン、
|
||||
リンクハンドラーも独自の `platforms` を宣言でき、項目レベルの platforms は
|
||||
トップレベルのリストを上書きします。トップレベルの `platforms` がないローカル
|
||||
プラグインは警告付きでリンクされます。
|
||||
|
||||
`command` の値は argv 配列です。Herdr はこれをシェル経由で実行しないため、
|
||||
コマンド自身がシェルを起動しない限りシェル展開はありません。言語固有の挙動は
|
||||
|
|
@ -192,6 +195,11 @@ herdr plugin log list --plugin example.layout
|
|||
ビルドコマンドを実行し、チェックアウトを Herdr 管理のプラグインデータの下に保存して
|
||||
登録します。非対話的なインストールには `--yes` を使ってください。GitHub 管理の
|
||||
プラグインを再インストールすると、その管理チェックアウトが置き換えられます。
|
||||
インストール済みおよびリンク済みのプラグインと、その有効・無効の状態は現在の
|
||||
ユーザー全体で共有され、すべての Herdr セッションから利用できます。Herdr サーバーが
|
||||
動作していないときでも `plugin install` と `plugin link` で登録できます。
|
||||
Herdr 0.7.3 の名前付きセッションだけにインストールしたプラグインは、再度 install
|
||||
または link してください。既存のプラグイン設定と状態はそのまま残ります。
|
||||
ローカルにリンクされたプラグインへの上書きインストールは拒否されます。先に
|
||||
ローカルプラグインを unlink または uninstall してください。`plugin install` と
|
||||
`plugin link` はプラグインの設定・状態ディレクトリを作成し、
|
||||
|
|
@ -226,6 +234,23 @@ Herdr のソケット環境変数は受け取りません。プラグインの
|
|||
`bun`、`lua` といった必要なシステムツールをドキュメントに書いてください。Herdr は
|
||||
ビルドの失敗を報告しますが、足りないツールチェーンをインストールすることはありません。
|
||||
|
||||
## スタートアップフック
|
||||
|
||||
`[[startup]]` コマンドは、Herdr がセッションを復元し、API ソケットの準備が整った後に、
|
||||
有効なプラグインごとに一度実行されます。ライブハンドオフで新しいサーバーが引き継いだ
|
||||
ときにも再実行されますが、クライアントの接続、設定の再読み込み、プラグインの link や
|
||||
enable では実行されません。Herdr はこれらを非同期で開始し、完了を通常のプラグイン
|
||||
コマンドログに記録します。スタートアップの失敗でサーバーが停止することはありません。
|
||||
|
||||
スタートアップフックは一度限りの初期化コマンドであり、監視されるデーモンではありません。
|
||||
フックはプラグインが所有する状態を復元し、必要な Herdr API を呼び出して終了してください。
|
||||
たとえば宣言型の Agent ビューを `HERDR_PLUGIN_STATE_DIR` に保存し、スタートアップフックで
|
||||
読み込んで再適用できます。
|
||||
|
||||
スタートアップフックは通常のランタイムプラグイン環境と
|
||||
`HERDR_PLUGIN_EVENT=startup` を受け取ります。インストールプレビューには、自動実行される
|
||||
コードを確認できるよう、すべてのスタートアップコマンドが表示されます。
|
||||
|
||||
## コマンドと環境
|
||||
|
||||
ランタイムコマンドは、プラグインディレクトリを作業ディレクトリとして実行されます。
|
||||
|
|
@ -233,8 +258,9 @@ Herdr は `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV=1`、
|
|||
`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、
|
||||
`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_CONTEXT_JSON`、そして利用可能なら
|
||||
`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID` を注入します。アクション
|
||||
コマンドは加えて `HERDR_PLUGIN_ACTION_ID` を受け取ります。イベントフックは
|
||||
`HERDR_PLUGIN_EVENT` と `HERDR_PLUGIN_EVENT_JSON` を、ペインコマンドは
|
||||
コマンドは加えて `HERDR_PLUGIN_ACTION_ID` を受け取ります。スタートアップフックと
|
||||
イベントフックは `HERDR_PLUGIN_EVENT`（スタートアップフックでは `startup`）を受け取り、
|
||||
イベントフックはさらに `HERDR_PLUGIN_EVENT_JSON` を、ペインコマンドは
|
||||
`HERDR_PLUGIN_ENTRYPOINT_ID` を受け取ります。
|
||||
|
||||
`HERDR_PLUGIN_ROOT` は、インストールまたはリンクされたプラグインディレクトリです。
|
||||
|
|
|
|||
|
|
@ -93,6 +93,8 @@ Herdr が resume するのは、現行の公式 Herdr インテグレーショ
|
|||
|
||||
これはスナップショット復元、ペイン履歴リプレイ、エージェントネイティブのセッション復元とは異なります。ハンドオフは現在のプロセスを生かし続けようとします。他の経路は、古いサーバーが停止した後に状態を再構築します。
|
||||
|
||||
ハンドオフが保護するのは、ペインの PTY とプロセス、エージェントの識別情報と永続メタデータ、交換後のサーバーに必要なプラグイン/セッション状態など、サーバーが所有する長寿命のセッション状態です。交換境界をまたぐ一時的な協調状態は保持しません。処理中の CLI/API リクエスト、wait、購読ストリーム、クライアントソケット、ペイン間メッセージは中断される可能性があるため、クライアントは再接続して再試行してください。
|
||||
|
||||
ライブハンドオフは実験的機能で、オプトインです:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ herdr api schema --output herdr-api.schema.json
|
|||
- ワークスペースの作成、一覧、フォーカス、名前変更、クローズ
|
||||
- タブの作成、一覧、フォーカス、名前変更、クローズ
|
||||
- ペインの一覧、調査、分割、入れ替え、フォーカス、リサイズ、名前変更、読み取り、クローズ、入力送信
|
||||
- CLI ヘルパーを通じたエージェントの一覧、調査、読み取り、送信、名前変更、フォーカス、起動、アタッチ
|
||||
- CLI ヘルパーを通じたエージェントの一覧、調査、読み取り、プロンプト、待機、名前変更、フォーカス、起動、アタッチ
|
||||
- フックやプラグインからのカスタムエージェント状態の報告
|
||||
- イベントの購読と、出力や状態変化の待機
|
||||
- 組み込みインテグレーションのインストールとアンインストール
|
||||
|
|
@ -77,7 +77,7 @@ herdr pane split w1:p1 --direction right --ratio 0.333
|
|||
エージェントを待つ:
|
||||
|
||||
```bash
|
||||
herdr wait agent-status w1:p1 --status done
|
||||
herdr agent wait w1:p1 --until done
|
||||
```
|
||||
|
||||
ペインの出力を読む:
|
||||
|
|
@ -102,12 +102,12 @@ herdr pane read w1:p2 --source recent --lines 50
|
|||
| ペイン | `pane.split`、`pane.swap`、`pane.move`、`pane.zoom`、`pane.layout`、`pane.process_info`、`pane.neighbor`、`pane.edges`、`pane.focus_direction`、`pane.resize`、`pane.list`、`pane.current`、`pane.get`、`pane.rename`、`pane.send_text`、`pane.send_keys`、`pane.send_input`、`pane.read`、`pane.graphics.info`、`pane.graphics.set`、`pane.graphics.clear`、`pane.graphics.stream`、`pane.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` |
|
||||
| ポップアップ | `popup.close` |
|
||||
| レイアウト | `layout.export`、`layout.apply`、`layout.set_split_ratio` |
|
||||
| エージェント | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send`、`agent.rename`、`agent.focus`、`agent.start` |
|
||||
| エージェント | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send_keys`、`agent.prompt`、`agent.wait`、`agent.rename`、`agent.focus`、`agent.start` |
|
||||
| イベント | `events.subscribe`、`events.wait` |
|
||||
| インテグレーション | `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` |
|
||||
|
||||
一部の CLI コマンドは、これらのメソッドの便利ラッパーです。たとえば `herdr agent wait` は、エージェントターゲットを解決してからペインのエージェント状態イベントを購読します。
|
||||
`agent.wait` はサーバー所有でイベント駆動です。解決したペイン占有者に固定されるため、置換されたエージェントが待機を満たすことはありません。`agent.prompt` は `until` と `timeout_ms` を持つ省略可能な `wait` オブジェクトを受け付けます。これにより、プロンプト送信と待機開始を 1 つのリクエストで行い、別々の呼び出し間の競合を避けられます。
|
||||
|
||||
`session.snapshot` は、独自のローカルランタイムキャッシュを持つクライアント向けに、一度限りのブートストラップスナップショットを返します。レスポンスには、バージョン/プロトコルメタデータ、フォーカス中のワークスペース/タブ/ペイン id、ワークスペース、タブ、ペイン、タブレイアウト、エージェントの各レコードが含まれます。これは購読ではありません。取得後はリソースイベントを購読し、そのイベントでローカルキャッシュを更新してください。再接続後やキャッシュが古い可能性がある場合は、`session.snapshot` を再度呼び出します。ワークスペースレコードには、関連付けられた worktree の出自情報も含まれます。リポジトリ全体の worktree 検出には引き続き `worktree.list` を使います。
|
||||
|
||||
|
|
@ -297,6 +297,80 @@ Worktree メソッドは Git チェックアウトを Herdr ワークスペー
|
|||
|
||||
worktree コマンドはライフサイクルイベントも発行します。`worktree.create` は `workspace.created`、`tab.created`、`pane.created`、`worktree.created` を発行します。`worktree.open` は `worktree.opened` を発行し、新しい Herdr ワークスペースを開いた場合はワークスペース/タブ/ペインの作成イベントも発行します。`worktree.remove` は `worktree.removed` を発行し、リンクされたワークスペースがまだ開いている場合は `workspace.closed` も発行します。
|
||||
|
||||
## エージェントビューのクエリ
|
||||
|
||||
`agent.view.set` は、組み込みの Agents ビューに一つの一時的な宣言型プロジェクションを
|
||||
設定します。エージェントの情報や現在の UI コンテキストが変わるたびに再評価されます。
|
||||
展開・折りたたみサイドバー、モバイルの Agents リスト、マウスターゲット、番号付き
|
||||
フォーカス、前後のエージェントへの移動順を制御します。`agent.list`、通知、検出、
|
||||
グローバルな要対応件数は変更しません。
|
||||
|
||||
現在表示中の Space にいるエージェント、または別の場所で対応が必要なエージェントを
|
||||
表示し、要対応度と直近の状態遷移で並べ替える例です:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "view_set",
|
||||
"method": "agent.view.set",
|
||||
"params": {
|
||||
"source": "plugin:example.agent-views",
|
||||
"label": "focus",
|
||||
"filter": {
|
||||
"op": "any",
|
||||
"filters": [
|
||||
{
|
||||
"op": "eq",
|
||||
"field": "workspace_id",
|
||||
"value": {"context": "current_workspace_id"}
|
||||
},
|
||||
{
|
||||
"op": "in",
|
||||
"field": "status",
|
||||
"values": ["blocked", "done"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"sort": [
|
||||
{"field": "attention", "order": "desc"},
|
||||
{"field": "state_change_seq", "order": "desc"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
フィルターノードの `op` には `all`、`any`、`not`、`eq`、`in`、`exists` を使います。
|
||||
組み込みフィールドは `status`、`workspace_id`、`tab_id`、`pane_id`、`agent`、
|
||||
`seen`、`state_change_seq` です。プラグインが報告したペインメタデータを絞り込むには、
|
||||
フィールドとして `{"token":"name"}` を使います。値には文字列、真偽値、符号なし整数、
|
||||
またはコンテキストオブジェクトを指定できます。コンテキスト値は
|
||||
`current_workspace_id` と `current_tab_id` で、対応する ID フィールドとの比較にだけ
|
||||
使えます。有効な status は `idle`、`working`、`blocked`、`done`、`unknown` です。
|
||||
`done` は idle かつ未確認の状態を表します。
|
||||
|
||||
ソートフィールドは `workspace_order`、`tab_order`、`pane_order`、`attention`、
|
||||
`status`、`agent`、`seen`、`state_change_seq`、または `{"token":"name"}` です。
|
||||
ソートは安定しており、指定順に評価され、`asc` または `desc` を受け付けます。値がない
|
||||
項目は値がある項目の後に残ります。`sort` を省略すると既存の
|
||||
`ui.agent_panel_sort` ポリシーが有効です。カスタムソートは設定を書き換えず、一時的に
|
||||
そのポリシーを置き換えます。
|
||||
|
||||
`source` は所有者を識別します。プラグインは `plugin:<HERDR_PLUGIN_ID>` を使います。
|
||||
所有元のプラグインが存在しないか無効な場合、Herdr は設定を拒否します。他の呼び出し元は
|
||||
独自の非 `plugin:` source を使えます。設定に成功すると以前のビューはアトミックに
|
||||
置き換えられます。ビューは clear または置換されるか、所有プラグインが disable、unlink、
|
||||
uninstall されるか、サーバーが終了するまで有効です。永続的な動作が必要なプラグインは、
|
||||
クエリを `HERDR_PLUGIN_STATE_DIR` に保存し、`[[startup]]` フックから再適用してください。
|
||||
|
||||
無条件で clear するか、指定した source がまだ所有している場合だけ clear できます:
|
||||
|
||||
```json
|
||||
{"id":"view_clear","method":"agent.view.clear","params":{}}
|
||||
{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}
|
||||
```
|
||||
|
||||
source が一致しない場合、アクティブなビューは変わりません。set と clear のレスポンスは
|
||||
`type: "agent_view"` で、`active`、`source`、任意の `label` を報告します。
|
||||
|
||||
## プラグイン API
|
||||
|
||||
プラグイン API は、実行可能なワークフローツールのための初期のホスト面です。プラグインは `herdr-plugin.toml` マニフェストを持つパッケージです。マニフェストは、共有可能なアクション、イベントフック、ターミナルペインのエントリーポイント、リンクハンドラーを宣言します。アクションとペインはマニフェスト専用です。ランタイムでのアクション登録とランタイムでの argv ペイン作成は v1 の範囲外です。
|
||||
|
|
@ -589,8 +663,8 @@ herdr pane read w1:p1 --source detection
|
|||
エージェントとスクリプトの協調には wait を使います。
|
||||
|
||||
```bash
|
||||
herdr wait agent-status w1:p1 --status done
|
||||
herdr wait agent-status w1:p1 --status blocked
|
||||
herdr agent wait w1:p1 --until done
|
||||
herdr agent wait w1:p1 --until blocked
|
||||
```
|
||||
|
||||
エージェントの wait は、任意のコマンドの完了ではなく意味的な状態を観測します。
|
||||
|
|
|
|||
|
|
@ -73,6 +73,9 @@ command = ["npm", "ci"]
|
|||
command = ["npm", "run", "build"]
|
||||
platforms = ["linux", "macos"]
|
||||
|
||||
[[startup]]
|
||||
command = ["node", "dist/restore.js"]
|
||||
|
||||
[[actions]]
|
||||
id = "apply"
|
||||
title = "Apply layout"
|
||||
|
|
@ -109,9 +112,10 @@ dots. Each id type must be unique inside a plugin. Herdr qualifies action ids
|
|||
as `plugin.id.action` when it needs a globally unique name.
|
||||
|
||||
Use `platforms = ["linux", "macos", "windows"]` to declare where the plugin
|
||||
can run. Build commands, actions, event hooks, panes, and link handlers can
|
||||
also declare their own `platforms`; item-level platforms override the top-level
|
||||
list. Local plugins without top-level `platforms` link with a warning.
|
||||
can run. Build commands, startup hooks, actions, event hooks, panes, and link
|
||||
handlers can also declare their own `platforms`; item-level platforms override
|
||||
the top-level list. Local plugins without top-level `platforms` link with a
|
||||
warning.
|
||||
|
||||
`command` values are argv arrays. Herdr does not run them through a shell, so
|
||||
there is no shell expansion unless your command starts a shell itself. Put
|
||||
|
|
@ -190,6 +194,11 @@ herdr plugin log list --plugin example.layout
|
|||
terminals, runs supported build commands, then stores the checkout under
|
||||
Herdr-managed plugin data and registers it. Use `--yes` for noninteractive
|
||||
installs. Reinstalling a GitHub-managed plugin replaces that managed checkout.
|
||||
Installed and linked plugins, including their enabled state, are global to the
|
||||
current user and available in every Herdr session. Both `plugin install` and
|
||||
`plugin link` can register plugins while no Herdr server is running. Plugins
|
||||
installed only in a named session on Herdr 0.7.3 must be installed or linked
|
||||
again. Existing plugin config and state remain in place.
|
||||
Installing over a locally linked plugin is refused; unlink or uninstall the
|
||||
local plugin first. `plugin install` and `plugin link` create the plugin's
|
||||
config and state directories, and `plugin config-dir <id>` prints the config
|
||||
|
|
@ -222,6 +231,24 @@ plugin context or Herdr socket env. Plugin authors should document required
|
|||
system tools such as `cargo`, `npm`, `bun`, or `lua`; Herdr reports build
|
||||
failures but does not install missing toolchains.
|
||||
|
||||
## Startup hooks
|
||||
|
||||
`[[startup]]` commands run once for each enabled plugin after Herdr restores the
|
||||
session and its API socket is ready. They run again when a new server takes over
|
||||
during live handoff, but not when a client attaches, config reloads, or a plugin
|
||||
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
|
||||
`HERDR_PLUGIN_STATE_DIR`, then read and reapply that view from its startup hook.
|
||||
|
||||
Startup hooks receive the normal runtime plugin environment and
|
||||
`HERDR_PLUGIN_EVENT=startup`. The install preview lists every startup command so
|
||||
users can review code that will run automatically.
|
||||
|
||||
## Commands and environment
|
||||
|
||||
Runtime commands run with the plugin directory as their working directory. Herdr
|
||||
|
|
@ -229,8 +256,10 @@ injects `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ENV=1`,
|
|||
`HERDR_PLUGIN_ID`, `HERDR_PLUGIN_ROOT`, `HERDR_PLUGIN_CONFIG_DIR`,
|
||||
`HERDR_PLUGIN_STATE_DIR`, `HERDR_PLUGIN_CONTEXT_JSON`, and any available
|
||||
`HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, and `HERDR_PANE_ID`. Action commands also
|
||||
receive `HERDR_PLUGIN_ACTION_ID`; event hooks receive `HERDR_PLUGIN_EVENT` and
|
||||
`HERDR_PLUGIN_EVENT_JSON`; pane commands receive `HERDR_PLUGIN_ENTRYPOINT_ID`.
|
||||
receive `HERDR_PLUGIN_ACTION_ID`; startup and event hooks receive
|
||||
`HERDR_PLUGIN_EVENT` (`startup` for startup hooks), event hooks additionally
|
||||
receive `HERDR_PLUGIN_EVENT_JSON`, and pane commands receive
|
||||
`HERDR_PLUGIN_ENTRYPOINT_ID`.
|
||||
|
||||
`HERDR_PLUGIN_ROOT` is the installed or linked plugin directory. Do not store
|
||||
user credentials or durable state there, because GitHub-installed plugin roots
|
||||
|
|
|
|||
|
|
@ -93,6 +93,8 @@ Live handoff is for update and remote attach flows that need to replace a runnin
|
|||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Live handoff is experimental and opt-in:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ The socket API can:
|
|||
- create, list, focus, rename, and close workspaces
|
||||
- create, list, focus, rename, and close tabs
|
||||
- list, inspect, split, swap, focus, resize, rename, read, close, and send input to panes
|
||||
- list, inspect, read, send to, rename, focus, start, and attach agents through CLI helpers
|
||||
- list, inspect, read, prompt, wait on, rename, focus, start, and attach agents through CLI helpers
|
||||
- report custom agent state from hooks and plugins
|
||||
- subscribe to events and wait for output or state changes
|
||||
- install and uninstall built-in integrations
|
||||
|
|
@ -81,7 +81,7 @@ herdr pane split w1:p1 --direction right --ratio 0.333
|
|||
Wait for an agent:
|
||||
|
||||
```bash
|
||||
herdr wait agent-status w1:p1 --status done
|
||||
herdr agent wait w1:p1 --until done
|
||||
```
|
||||
|
||||
Read pane output:
|
||||
|
|
@ -106,12 +106,12 @@ Raw socket method names use dot notation:
|
|||
| Pane | `pane.split`, `pane.swap`, `pane.move`, `pane.zoom`, `pane.layout`, `pane.process_info`, `pane.neighbor`, `pane.edges`, `pane.focus_direction`, `pane.resize`, `pane.list`, `pane.current`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.graphics.info`, `pane.graphics.set`, `pane.graphics.clear`, `pane.graphics.stream`, `pane.report_agent`, `pane.report_agent_session`, `pane.report_metadata`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
|
||||
| Popup | `popup.close` |
|
||||
| Layout | `layout.export`, `layout.apply`, `layout.set_split_ratio` |
|
||||
| Agent | `agent.list`, `agent.get`, `agent.read`, `agent.explain`, `agent.send`, `agent.rename`, `agent.focus`, `agent.start` |
|
||||
| Agent | `agent.list`, `agent.get`, `agent.read`, `agent.explain`, `agent.send_keys`, `agent.prompt`, `agent.wait`, `agent.rename`, `agent.focus`, `agent.start`, `agent.view.set`, `agent.view.clear` |
|
||||
| Events | `events.subscribe`, `events.wait` |
|
||||
| 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` |
|
||||
|
||||
Some CLI commands are conveniences around these methods. For example, `herdr agent wait` resolves an agent target and then subscribes to pane agent state events.
|
||||
`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.
|
||||
|
||||
`session.snapshot` returns a one-time bootstrap snapshot for clients that keep
|
||||
their own local runtime cache. The response includes version/protocol metadata,
|
||||
|
|
@ -366,19 +366,96 @@ Use at most one of `workspace_id` or `cwd` for `worktree.list`, `worktree.create
|
|||
|
||||
Worktree commands also emit lifecycle events. `worktree.create` emits `workspace.created`, `tab.created`, `pane.created`, and `worktree.created`. `worktree.open` emits `worktree.opened`, and it also emits workspace/tab/pane creation events when it opens a new Herdr workspace. `worktree.remove` emits `worktree.removed`; if the linked workspace is still open, it also emits `workspace.closed`.
|
||||
|
||||
## Agent view queries
|
||||
|
||||
`agent.view.set` installs one transient declarative projection for the built-in
|
||||
Agents view. The projection is reevaluated whenever agent facts or current UI
|
||||
context change. It controls the expanded and collapsed sidebar, mobile Agents
|
||||
list, mouse targets, indexed focus, and next/previous Agent navigation. It does
|
||||
not change `agent.list`, notifications, detection, or global attention counts.
|
||||
|
||||
Show agents in the currently presented Space or agents needing attention
|
||||
elsewhere, then order by attention and most recent state transition:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "view_set",
|
||||
"method": "agent.view.set",
|
||||
"params": {
|
||||
"source": "plugin:example.agent-views",
|
||||
"label": "focus",
|
||||
"filter": {
|
||||
"op": "any",
|
||||
"filters": [
|
||||
{
|
||||
"op": "eq",
|
||||
"field": "workspace_id",
|
||||
"value": {"context": "current_workspace_id"}
|
||||
},
|
||||
{
|
||||
"op": "in",
|
||||
"field": "status",
|
||||
"values": ["blocked", "done"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"sort": [
|
||||
{"field": "attention", "order": "desc"},
|
||||
{"field": "state_change_seq", "order": "desc"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Filter nodes use `op` values `all`, `any`, `not`, `eq`, `in`, or `exists`.
|
||||
Built-in filter fields are `status`, `workspace_id`, `tab_id`, `pane_id`,
|
||||
`agent`, `seen`, and `state_change_seq`. Use `{"token":"name"}` as a field to
|
||||
filter plugin-reported pane metadata. Values are strings, booleans, unsigned
|
||||
numbers, or a context object. Context values are `current_workspace_id` and
|
||||
`current_tab_id`, and may only be compared to the matching ID field. Effective
|
||||
status values are `idle`, `working`, `blocked`, `done`, and `unknown`; `done`
|
||||
means idle and not yet seen.
|
||||
|
||||
Sort fields are `workspace_order`, `tab_order`, `pane_order`, `attention`,
|
||||
`status`, `agent`, `seen`, `state_change_seq`, or `{"token":"name"}`. Sorts are
|
||||
stable, evaluated in order, and accept `asc` or `desc`. Missing values stay
|
||||
after present values. When `sort` is omitted, the existing
|
||||
`ui.agent_panel_sort` policy remains active. A custom sort temporarily replaces
|
||||
that policy without rewriting config.
|
||||
|
||||
`source` identifies the owner. Plugins use `plugin:<HERDR_PLUGIN_ID>`; Herdr
|
||||
rejects plugin-owned sets when that plugin is missing or disabled. Other callers
|
||||
may use their own non-`plugin:` source. A successful set atomically replaces the
|
||||
previous view. The view lasts until it is cleared, replaced, its owning plugin
|
||||
is disabled, unlinked, or uninstalled, or the server exits. Plugins that want
|
||||
durable behavior should save the query under `HERDR_PLUGIN_STATE_DIR` and
|
||||
reapply it from a `[[startup]]` hook.
|
||||
|
||||
Clear unconditionally, or only when the named source still owns the view:
|
||||
|
||||
```json
|
||||
{"id":"view_clear","method":"agent.view.clear","params":{}}
|
||||
{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}
|
||||
```
|
||||
|
||||
A source mismatch leaves the active view unchanged. Set and clear responses use
|
||||
`type: "agent_view"` and report `active`, `source`, and optional `label`.
|
||||
|
||||
## 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
|
||||
shareable actions, event hooks, terminal pane entrypoints, and link handlers.
|
||||
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.
|
||||
|
||||
Installed and linked plugins persist across restarts. Herdr writes a
|
||||
`plugins.json` registry file alongside `session.json` on `plugin.link`,
|
||||
`plugin.unlink`, `plugin.enable`, and `plugin.disable`. The
|
||||
`herdr plugin install` CLI also writes the same registry when Herdr is not
|
||||
running, then startup loads it automatically. On startup, Herdr re-reads each
|
||||
`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.
|
||||
|
||||
|
|
@ -721,8 +798,8 @@ herdr pane read w1:p1 --source detection
|
|||
Use waits to coordinate agents and scripts.
|
||||
|
||||
```bash
|
||||
herdr wait agent-status w1:p1 --status done
|
||||
herdr wait agent-status w1:p1 --status blocked
|
||||
herdr agent wait w1:p1 --until done
|
||||
herdr agent wait w1:p1 --until blocked
|
||||
```
|
||||
|
||||
Agent waits observe semantic state, not arbitrary command completion.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
title: 智能体自动化
|
||||
description: 使用 Herdr 的布局、窗格和智能体原语,从脚本或其他智能体协调编码智能体。
|
||||
---
|
||||
|
||||
Herdr 可以作为编码智能体的自动化层。脚本可以控制智能体,一个智能体也可以给其他智能体分配工作、检查状态并收集结果。关键是为任务选择正确的原语。
|
||||
|
||||
## 三种原语
|
||||
|
||||
| 原语 | 职责 |
|
||||
| --- | --- |
|
||||
| 布局（`workspace`、`tab` 和窗格拓扑） | 创建和组织终端位置。 |
|
||||
| 窗格 | 控制原始终端:运行命令、发送输入、读取输出和等待输出。 |
|
||||
| 智能体 | 按名称或窗格以及生命周期状态控制已识别的编码智能体。 |
|
||||
|
||||
无论是否包含智能体,窗格都可以存在。智能体是 Herdr 在窗格中识别出的当前进程。因此,`agent start` 需要一个现有 shell 窗格,绝不会创建、拆分或移动布局。
|
||||
|
||||
创建工作区时也会创建第一个标签页和根窗格;创建标签页时会创建它的根窗格。第一个进程应使用返回的窗格 ID,只有布局需要另一个终端时才进行拆分。
|
||||
|
||||
创建命令输出 JSON。请从响应中读取 ID,不要猜测:
|
||||
|
||||
```bash
|
||||
created=$(herdr workspace create --cwd ~/project --label api --no-focus)
|
||||
pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')
|
||||
|
||||
split=$(herdr pane split "$pane_id" --direction right --no-focus)
|
||||
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
||||
```
|
||||
|
||||
`workspace create` 返回 `.result.workspace`、`.result.tab` 和 `.result.root_pane`;`tab create` 返回 `.result.tab` 和 `.result.root_pane`;`pane split` 把新窗格返回为 `.result.pane`。
|
||||
|
||||
把窗格移动到另一个工作区会改变带工作区前缀的窗格 ID。执行 `pane move` 后,请继续使用 `.result.move_result.pane.pane_id`;旧值保留在 `.result.move_result.previous_pane_id`。运行中的进程会保留启动时的 Herdr 环境,但旧的 `HERDR_PANE_ID` 会继续作为该终端的别名,所以 `--current` 仍可安全使用。移动后发起的新命令仍可通过智能体名称解析,但已经进行中的等待会以 `agent_not_running` 结束。
|
||||
|
||||
对于 shell、测试、服务器、CI 监视器和其他普通终端进程,使用窗格命令。当 Herdr 需要理解正在运行的是哪个智能体,或它处于 `working`、`blocked`、`done`、`idle`、`unknown` 中的哪个状态时,使用智能体命令。
|
||||
|
||||
## 智能体身份与启动
|
||||
|
||||
`w1:p2` 这样的窗格 ID 标识终端位置。`reviewer` 这样的智能体名称是该窗格中当前智能体的便捷别名。名称必须匹配 `[a-z][a-z0-9_-]{0,31}`,并在实时智能体中唯一。智能体退出、被释放或被替换时,别名会被清除;它不会永久重命名窗格。
|
||||
|
||||
智能体命令既可以接受唯一的实时名称,也可以接受当前托管该智能体的窗格 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`。`--` 后的参数会原样传给该可执行文件。
|
||||
|
||||
`agent start` 只有在 Herdr 于同一终端检测到预期智能体,并确认它可接受交互输入后才返回。默认等待启动 30 秒;`--timeout` 必须大于 3000 且不超过 300000 毫秒。
|
||||
|
||||
```bash
|
||||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
```
|
||||
|
||||
手动启动的智能体也会被自动检测,可以用窗格 ID 指定。当需要一个稳定、易读的目标时,给它命名:
|
||||
|
||||
```bash
|
||||
herdr agent get w1:p2
|
||||
herdr agent rename w1:p2 reviewer
|
||||
```
|
||||
|
||||
## 选择控制界面
|
||||
|
||||
| 目标 | 命令 |
|
||||
| --- | --- |
|
||||
| 运行并提交 shell 命令 | `pane run` |
|
||||
| 发送不带 Enter 的纯文本 | `pane send-text` |
|
||||
| 发送终端按键或修饰键组合 | `pane send-keys` |
|
||||
| 等待文本或正则表达式 | `pane wait-output` |
|
||||
| 在现有窗格中启动受支持的智能体 | `agent start` |
|
||||
| 提交提示,并可选择等待 | `agent prompt` |
|
||||
| 向智能体交互界面发送按键 | `agent send-keys` |
|
||||
| 等待智能体生命周期状态 | `agent wait` |
|
||||
|
||||
`agent prompt` 会提交文本和编码后的 Enter,并遵循终端当前的 bracketed paste 模式。即使智能体正在 working 也可以提交。使用 `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` 一起使用。
|
||||
|
||||
`idle` 表示智能体正等待输入,且其标签页已在聚焦的 Herdr 界面中显示。`done` 是相同的底层 idle 状态,但用于后台工作完成后,直到该标签页获得焦点或 `pane focus` / `agent focus` 指向它。仅通过 CLI 读取不会把它标记为已查看。`blocked` 表示 Herdr 识别到了审批或提问界面。`unknown` 表示智能体存在,但 Herdr 无法可靠判断其生命周期;它不代表工作成功完成。区别重要时,请指定精确的 `--until` 状态。
|
||||
|
||||
`pane wait-output` 不解释智能体生命周期。它轮询选定的终端快照并立即进行第一次搜索,所以已经存在的文本也会匹配。默认来源名是 `recent`;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。`--lines` 可以修改这个行数限制;`--regex` 使用 Rust 正则表达式语法并逐行匹配。
|
||||
|
||||
在 CLI 中,`pane read` 和 `agent read` 都直接打印终端文本。默认输出去除 ANSI 转义的 UTF-8 文本;来源包含样式时,使用 `--format ansi` 或 `--ansi` 保留终端转义。`detection` 来源始终是纯文本。对 recent 类来源,`--lines N` 会在可选的取消折行之前选择最后 N 个已渲染终端行;省略时默认读取 80 行。对 `visible` 和 `detection`,省略 `--lines` 会返回完整快照,指定时保留按换行分隔的最后 N 行。socket API 在 `.result.read.text` 返回文本。
|
||||
|
||||
## 已知注意事项:备用屏幕输出
|
||||
|
||||
Claude Code 和 OpenCode 等全屏智能体可能会在终端的备用屏幕中绘制。备用屏幕中的行不会进入 Herdr 的主机回滚缓冲区。如果回复超出可见窗格,`recent` 和 `recent-unwrapped` 无法恢复应用已不再显示的行;增大 `--lines` 也无法获取这些历史内容。字体较大或窗格较小时更容易遇到此限制。
|
||||
|
||||
可以要求智能体简洁回复、扩大窗格或使用较小字体,也可以使用智能体自身的记录和滚动控件。在智能体内部滚动后,使用 `--source visible` 读取它当前绘制的页面。
|
||||
|
||||
成功的 `agent start`、`agent prompt` 和 `agent wait` 会在 `.result.agent` 返回当前智能体。`pane wait-output` 返回 `.result.pane_id`、`.result.matched_line` 以及位于 `.result.read` 的匹配快照。
|
||||
|
||||
等待命令没有默认超时,可能无限等待。超时或服务器错误会把 JSON 错误写到 stderr 并以状态 1 退出;CLI 语法错误以状态 2 退出。
|
||||
|
||||
## 示例
|
||||
|
||||
启动辅助智能体,分配工作,并等待该工作结束:
|
||||
|
||||
```bash
|
||||
split=$(herdr pane split --current --direction right --no-focus)
|
||||
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
|
||||
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
|
||||
herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
|
||||
herdr agent read reviewer --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
等待智能体请求输入,检查内容,再操作其交互界面:
|
||||
|
||||
```bash
|
||||
herdr agent wait reviewer --until blocked --timeout 120000
|
||||
herdr agent read reviewer --source recent-unwrapped --lines 80
|
||||
herdr agent send-keys reviewer esc
|
||||
```
|
||||
|
||||
运行普通进程并等待输出,而不把它当作智能体:
|
||||
|
||||
```bash
|
||||
herdr pane run w1:p3 "just test --watch"
|
||||
herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000
|
||||
```
|
||||
|
||||
完整命令和选项列表见 [CLI 参考](/zh-cn/docs/cli-reference/)。Shell 补全也能以交互方式显示同一命令树。
|
||||
|
|
@ -58,7 +58,7 @@ claude
|
|||
|
||||
## 面向智能体的参考
|
||||
|
||||
完整的命令指南就在技能文件本身。它涵盖窗格 ID、`pane split`、`pane run`、`pane read`、`wait output`、`wait agent-status`、工作区和标签页命令,以及协作配方。
|
||||
完整的命令指南就在技能文件本身。它涵盖窗格 ID、`pane split`、`pane run`、`pane read`、`pane wait-output`、`agent wait`、工作区和标签页命令,以及协作配方。
|
||||
|
||||
在这里阅读源文件:
|
||||
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ description: 了解 Herdr 能检测什么、智能体状态如何工作,以及
|
|||
|
||||
Herdr 为同时运行多个编程智能体而生。每个智能体都待在一个真实的终端窗格里,shell、日志、提示符和运行中的进程都完好无损。Herdr 跟踪哪些窗格里有智能体,把它们的状态汇总到标签页和工作区,让你直接跳到需要关注的窗格,而不是手动轮询每个终端。
|
||||
|
||||
要从脚本或另一个智能体协调它们,请参阅[智能体自动化](/zh-cn/docs/agent-automation/)。
|
||||
|
||||
## 受支持的智能体
|
||||
|
||||
常见编程智能体开箱即用地支持自动检测。重要的区别不在于 Herdr 能不能看到某个智能体,而在于允许哪个信号来决定 `idle`、`working` 和 `blocked`。
|
||||
|
|
@ -47,7 +49,7 @@ Claude Code、Codex、GitHub Copilot CLI、Droid、Qoder CLI 和 Cursor Agent CL
|
|||
|
||||
## 虚拟机与沙箱包装器
|
||||
|
||||
在 Linux 上,VM、Bubblewrap 或 `fence` 之类的包装器可能把真实的智能体进程从宿主的 `/proc` 中隐藏起来。在命令上设置 `HERDR_AGENT=<agent>`,例如 `HERDR_AGENT=claude fence -- claude`,告诉 Herdr 该使用哪个已有智能体的屏幕清单。这个提示的作用范围只限于那个前台进程;除非所有继承它的前台进程都应被视为该智能体,否则不要在 shell 里全局 export。
|
||||
在 Linux 和 macOS 上,宿主可见的包装器可能会向 Herdr 隐藏真实的智能体进程。在包装器命令上设置 `HERDR_AGENT=<agent>`,告诉 Herdr 应使用哪个已有智能体的屏幕清单。例如,在 Linux 上运行 `HERDR_AGENT=claude fence -- claude`,或在 macOS 上运行 `HERDR_AGENT=claude nono run --profile claude-code -- claude`。这个提示的作用范围只限于该前台进程;仅在 VM 或容器内部设置时 Herdr 无法看到它,而且除非所有继承的前台进程都应被视为该智能体,否则不要全局 export。
|
||||
|
||||
## blocked 状态
|
||||
|
||||
|
|
@ -110,7 +112,7 @@ herdr agent rename w1:p1 reviewer
|
|||
herdr agent rename reviewer --clear
|
||||
```
|
||||
|
||||
目标可以是终端 ID、唯一的智能体名称、检测到或上报的智能体标签,以及旧式窗格 ID。
|
||||
目标使用唯一的实时智能体名称,或当前承载该智能体的窗格 ID。终端 ID 和单独的智能体 kind 标签不能作为目标。
|
||||
|
||||
## 自定义状态标签
|
||||
|
||||
|
|
@ -131,24 +133,6 @@ herdr pane report-metadata w1:p1 \
|
|||
|
||||
智能体侧边栏行也可以选择使用 `terminal_title` 或 `terminal_title_stripped`;两者都不在默认行中。前者显示经过安全规范化的最新 OSC 0/2 终端标题,后者会移除开头一个已识别的活动或旋转指示符字形及其后的空白。这些值由 Herdr 服务器所有,冷重启后不会保留,并且独立于元数据标题和语义智能体状态。因此,如果移除后的文本不变,旋转动画可以改变原始标题而不触发窗格更新。
|
||||
|
||||
## 从 CLI 启动智能体
|
||||
|
||||
当你希望一个终端被当作智能体目标时,使用 `herdr agent ...` 命令。智能体目标会出现在 `agent list` 中,可以按智能体名称读取或发送输入,可以按智能体状态等待,也可以被直接附加。
|
||||
|
||||
从脚本向 Herdr 中启动一个智能体:
|
||||
|
||||
```bash
|
||||
herdr agent start reviewer --cwd ~/project --split right -- pi
|
||||
```
|
||||
|
||||
也可以把该智能体放进特定的工作区或标签页:
|
||||
|
||||
```bash
|
||||
herdr agent start docs --workspace w1 --tab w1:t1 -- claude
|
||||
```
|
||||
|
||||
普通终端、服务器、测试、shell 和底层终端输入请使用 `herdr pane ...` 命令。例如跑 `cargo test` 用 `pane split` 和 `pane run`,而不是 `agent start`,除非那个终端就是有意要当作智能体目标。
|
||||
|
||||
## 直接附加到智能体
|
||||
|
||||
把当前终端附加到某一个智能体终端,而不是完整的 Herdr UI:
|
||||
|
|
|
|||
|
|
@ -126,6 +126,8 @@ herdr workspace close <workspace_id>
|
|||
herdr workspace create --cwd ~/project --label api --no-focus
|
||||
```
|
||||
|
||||
工作区是顶层项目或工作上下文。创建工作区也会创建第一个标签页和根窗格。JSON 响应中的 `.result.workspace.workspace_id`、`.result.tab.tab_id` 和 `.result.root_pane.pane_id` 是对应 ID。
|
||||
|
||||
## Worktree
|
||||
|
||||
```bash
|
||||
|
|
@ -150,6 +152,10 @@ herdr tab rename <tab_id> <label>
|
|||
herdr tab close <tab_id>
|
||||
```
|
||||
|
||||
标签页是工作区内的另一个终端布局。不指定 `--workspace` 时,`tab create` 使用活动工作区;如果没有活动工作区则失败。JSON 响应中的 `.result.tab.tab_id` 和 `.result.root_pane.pane_id` 是对应 ID。
|
||||
|
||||
创建工作区、标签页和拆分窗格默认不改变焦点。`--focus` 选择新布局;`--no-focus` 显式表达默认行为。不指定 `--cwd` 时,新终端遵循 `terminal.new_cwd` 设置,默认跟随来源窗格或工作区。每个 `--env KEY=VALUE` 在新的根 shell 中添加或替换一个环境变量。
|
||||
|
||||
## 窗格
|
||||
|
||||
```bash
|
||||
|
|
@ -173,14 +179,20 @@ herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--f
|
|||
herdr pane close <pane_id>
|
||||
```
|
||||
|
||||
接受 `--current` 的窗格命令在 Herdr 窗格内运行时使用调用方的 `HERDR_PANE_ID`。对 `pane split` 而言,显式窗格 ID 或 `--pane ID` 拆分该窗格,`--current` 拆分调用方窗格,省略目标则使用 UI 当前聚焦的窗格。拆分响应中的新窗格 ID 位于 `.result.pane.pane_id`。
|
||||
|
||||
执行 `pane move` 后,后续命令应使用 `.result.move_result.pane.pane_id`。跨工作区移动会改变带工作区前缀的窗格 ID;旧值保留在 `.result.move_result.previous_pane_id`。运行中进程的 `HERDR_PANE_ID`、`HERDR_TAB_ID` 和 `HERDR_WORKSPACE_ID` 保持启动时的值,但 Herdr 会把旧窗格 ID 保留为该终端的别名,所以使用 `--current` 的窗格命令仍能解析它。实时智能体名称也会跟随终端。
|
||||
|
||||
读取输出:
|
||||
|
||||
```bash
|
||||
herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N]
|
||||
herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
|
||||
herdr pane read <pane_id> --source visible --ansi
|
||||
herdr pane read <pane_id> --source recent-unwrapped --lines 120
|
||||
```
|
||||
|
||||
`pane read` 直接打印 UTF-8 终端文本。默认去除 ANSI 转义;来源包含样式时,使用 `--format ansi` 或 `--ansi` 保留。`detection` 来源始终是纯文本。对 recent 类来源,`--lines N` 会在可选的取消折行之前选择最后 N 个已渲染终端行;省略时默认读取 80 行。对 `visible` 和 `detection`,省略 `--lines` 会返回完整快照,指定时保留按换行分隔的最后 N 行。`agent read` 使用相同的输出和行数行为。
|
||||
|
||||
发送输入:
|
||||
|
||||
```bash
|
||||
|
|
@ -191,7 +203,9 @@ herdr pane run <pane_id> <command>
|
|||
|
||||
`<key>` 使用 Herdr 的组合键语法: `a` 这类普通可打印键,`enter`、`tab`、`esc`、`backspace`、`left`、`right`、`up`、`down` 这类特殊键,`ctrl+h`、`control+j`、`alt+x`、`shift+tab` 这类修饰组合键,`f1` 这类功能键,以及 `minus`、`plus`、`backtick` 这类命名标点。旧式的 `C-c` 和 `c-c` 作为 `ctrl+c` 的别名被接受。
|
||||
|
||||
`pane run` 把文本和回车作为一个原子操作提交。发送命令时优先用它,而不是 `send-text` 加 `send-keys Enter`。
|
||||
标准拼写是 `esc`;也接受 `escape`。
|
||||
|
||||
`pane run` 会遵循当前的 bracketed paste 模式,并把文本和 Enter 作为一个原子操作提交。发送命令时优先用它,而不是 `send-text` 加 `send-keys Enter`;单独的发送操作仍是底层操作,不会提交命令。
|
||||
|
||||
从自定义钩子上报智能体状态:
|
||||
|
||||
|
|
@ -204,8 +218,23 @@ herdr pane report-agent <pane_id> \
|
|||
[--seq N] \
|
||||
[--agent-session-id ID] \
|
||||
[--agent-session-path PATH]
|
||||
|
||||
herdr pane report-agent-session <pane_id> \
|
||||
--source ID \
|
||||
--agent LABEL \
|
||||
[--seq N] \
|
||||
[--agent-session-id ID] \
|
||||
[--agent-session-path PATH] \
|
||||
[--session-start-source SOURCE]
|
||||
|
||||
herdr pane release-agent <pane_id> \
|
||||
--source ID \
|
||||
--agent LABEL \
|
||||
[--seq N]
|
||||
```
|
||||
|
||||
`report-agent-session` 只更新原生会话身份,不上报生命周期状态。`release-agent` 在智能体进程退出时结束该来源的生命周期权威。
|
||||
|
||||
当官方集成上报了原生会话引用时,`pane get`、`pane list`、`agent get` 和 `agent list` 会包含一个只读的 `agent_session` 对象。没有存储原生会话引用时,该字段被省略。
|
||||
|
||||
当 Herdr 能解析控制窗格的前台进程的 cwd 时,这些命令会包含 `foreground_cwd`。已有的 `cwd` 字段仍然是用于标签和 follow-cwd 行为的窗格/工作区 cwd。
|
||||
|
|
@ -237,23 +266,34 @@ herdr pane report-metadata <pane_id> \
|
|||
|
||||
## 智能体
|
||||
|
||||
窗格与智能体的模型和完整协调示例见[智能体自动化](/zh-cn/docs/agent-automation/)。
|
||||
|
||||
```bash
|
||||
herdr agent list
|
||||
herdr agent get <target>
|
||||
herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
|
||||
herdr agent send <target> <text>
|
||||
herdr agent send-keys <target> <key> [key ...]
|
||||
herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
|
||||
herdr agent rename <target> <name>|--clear
|
||||
herdr agent focus <target>
|
||||
herdr agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
|
||||
herdr agent wait <target> [--until STATUS]... [--timeout MS]
|
||||
herdr agent attach <target> [--takeover]
|
||||
herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
|
||||
herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
|
||||
herdr agent explain <target> [--json|--verbose]
|
||||
herdr agent explain --file PATH --agent LABEL [--json|--verbose]
|
||||
```
|
||||
|
||||
智能体目标可以是终端 ID、唯一的智能体名称、检测到或上报的智能体标签,以及旧式窗格 ID。名称和标签是智能体的身份。终端 ID 和旧式窗格 ID 是底层的逃生舱。
|
||||
智能体目标只能是唯一的实时智能体名称,或当前承载该智能体的窗格 ID。终端 ID 和单独的智能体 kind 标签不能作为目标。通过 `agent start` 启动的智能体必须有名称;手动启动的智能体保持未命名,通过窗格 ID 寻址。
|
||||
|
||||
`agent read` 读取解析出的终端流。`agent send` 向该流写入字面文本。`agent get`、`agent focus`、`agent wait` 和 `agent attach` 要求解析出的终端具有智能体身份。`agent rename` 可以赋予这个身份。
|
||||
`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 或被替换时清除;短暂的检测不确定不会清除它。
|
||||
|
||||
start 只有在预期智能体占用同一终端并可接受交互输入后才返回。默认启动超时是 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`。
|
||||
|
||||
`idle` 表示智能体在等待输入,且其标签页已在聚焦的 Herdr 界面中显示。`done` 是相同的底层 idle 状态,用于未查看的后台工作完成后。聚焦该标签页或用 `pane focus` / `agent focus` 指向它会标记为已查看;仅通过 CLI 读取不会改变它。`blocked` 表示 Herdr 识别到审批或提问界面。`unknown` 表示智能体存在但无法可靠分类,不代表工作成功。
|
||||
|
||||
`agent send-keys` 发送 `enter`、`up`、`esc`、`ctrl+c` 等逻辑按键。Herdr 会在写入任何字节前验证所有按键。`agent read` 读取解析出的终端流,`agent rename` 为已检测到的智能体命名。
|
||||
|
||||
`agent explain` 请求运行中的服务器对屏幕检测所用的同一份底部缓冲区检测快照进行分类,因此实时输出反映服务器生效的清单缓存。因为它使用 `agent.explain` socket 方法,升级 Herdr 后,请先重启或交接到更新后的服务器,再使用实时 explain。用 `--file PATH --agent LABEL` 可以改为在本地解释一份保存的样本。默认输出显示智能体、最终状态、清单来源和版本、匹配的规则及其区域证据,以及任何回退、跳过或警告原因。加 `--verbose` 可以看到可见证据标志、缓存的远程版本、本地覆盖的遮蔽情况、远程更新状态,以及带匹配器和区域证据的完整已评估规则列表。提交问题报告或写测试时加 `--json`。
|
||||
|
||||
|
|
@ -270,21 +310,19 @@ herdr terminal title clear
|
|||
从直接附加中用 `ctrl+b q` 分离。用 `ctrl+b ctrl+b` 发送字面的 `ctrl+b`。
|
||||
`terminal title clear` 恢复 Herdr 默认的外层终端窗口标题。
|
||||
|
||||
## 等待
|
||||
## 输出等待
|
||||
|
||||
等待窗格中的输出:
|
||||
|
||||
```bash
|
||||
herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]
|
||||
herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]
|
||||
```
|
||||
|
||||
等待窗格的智能体状态:
|
||||
普通命令和服务器用 `pane wait-output`。编程智能体用 `agent wait`。
|
||||
|
||||
```bash
|
||||
herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]
|
||||
```
|
||||
`pane wait-output` 会立即检查所选快照,所以已经存在的输出也能匹配。默认来源名是 `recent`;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。`--lines` 可以修改这个行数限制。`--match` 在单行中查找字面子串;`--regex` 使用 Rust 正则表达式语法并逐行匹配。
|
||||
|
||||
普通命令和服务器用 `wait output`。编程智能体用 `wait agent-status`。
|
||||
`pane wait-output`、`agent wait` 和 `agent prompt --wait` 在省略 `--timeout` 时会无限等待。超时或服务器错误以 JSON 写到 stderr,退出状态为 1。CLI 用法错误的退出状态为 2。
|
||||
|
||||
## 集成
|
||||
|
||||
|
|
@ -389,6 +427,8 @@ herdr plugin pane close <pane_id>
|
|||
| `recent-unwrapped` | 不带软折行的最近回滚内容。最适合日志。 |
|
||||
| `detection` | 智能体屏幕检测使用的底部缓冲区快照。 |
|
||||
|
||||
此表描述读取时的含义。仅对 `pane wait-output` 而言,`recent` 和 `recent-unwrapped` 都搜索 recent 的未折行快照,默认写法仍是 `recent`。
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 用途 |
|
||||
|
|
|
|||
|
|
@ -295,6 +295,18 @@ Space 行支持以下内置 token：
|
|||
|
||||
token 会按配置顺序渲染。Herdr 通常使用 ` · ` 分隔相邻值，并在 `state_icon` 后使用一个空格。缺失值及其分隔符会消失；当一行中的所有 token 都没有值时，该行会消失。每个布局最多可包含 16 行，每行最多可包含 16 个 token。
|
||||
|
||||
也可以用内联样式表定义 token：
|
||||
|
||||
```toml
|
||||
[ui.sidebar.agents]
|
||||
rows = [
|
||||
["state_icon", { token = "workspace", bold = false }, "tab"],
|
||||
[{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }],
|
||||
]
|
||||
```
|
||||
|
||||
`fg` 只接受严格的 `#RGB` 或 `#RRGGBB`，`bold` 和 `dim` 接受布尔值。省略字段会保留上下文样式；显式 `false` 会移除对应修饰。样式只作用于当前出现位置。为 `git_status` 设置 `fg` 后，ahead 和 behind 会使用同一种颜色，而不是默认的绿色和红色。token 样式不会改变分隔符或行背景。
|
||||
|
||||
`row_gap` 分别控制 Agent 和 Space 面板中条目之间的空白终端行数。默认值为 `0`，会紧密排列条目；设为 `1` 可恢复之前的间距。它不会在 `rows` 声明的内容行之间添加间距。连续缩进的 worktree 子项仍会作为一个 Space 组紧密排列。
|
||||
|
||||
在 `rows_by_agent` 下为已知智能体覆盖完整的 Agent 布局：
|
||||
|
|
@ -334,7 +346,9 @@ herdr pane report-metadata <pane_id> \
|
|||
--token summary="reviewing authentication"
|
||||
```
|
||||
|
||||
自定义 Space token 可用同样的方式通过 `herdr workspace report-metadata` 报告。未报告的自定义 token 会直接消失。元数据报告方只提供值，不能选择行或样式。有关清除、顺序和过期值的信息，请参阅 [CLI 参考：报告元数据](/docs/cli-reference/#panes)。
|
||||
自定义 Space token 可用同样的方式通过 `herdr workspace report-metadata` 报告。未报告的自定义 token 会直接消失。
|
||||
|
||||
元数据上报方只提供值；样式由本地侧边栏配置控制。有关限制、清除、顺序和过期值的信息，请参阅 [CLI 参考：报告元数据](/docs/cli-reference/#panes)。
|
||||
|
||||
侧边栏行设置仅影响展开的桌面侧边栏。折叠视图和移动视图仍使用紧凑布局。
|
||||
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ Herdr 把内置扩展写入:
|
|||
~/.pi/agent/extensions/herdr-agent-state.ts
|
||||
```
|
||||
|
||||
如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts`。extensions 目录必须已经存在。卸载只删除那个扩展文件。
|
||||
如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts`。如果 Pi agent 目录已经存在,Herdr 会创建 extensions 目录。卸载只删除那个扩展文件。
|
||||
|
||||
## OMP
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ Herdr 把内置扩展写入:
|
|||
~/.omp/agent/extensions/herdr-omp-agent-state.ts
|
||||
```
|
||||
|
||||
如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts`。extensions 目录必须已经存在。卸载只删除那个扩展文件。
|
||||
如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts`。如果 OMP agent 目录已经存在,Herdr 会创建 extensions 目录。卸载只删除那个扩展文件。
|
||||
|
||||
OMP 集成通过 Herdr 的 socket API 上报智能体标签 `omp`、生命周期状态和原生会话身份。它不需要对 `omp` 可执行文件做原生进程检测,并且 Herdr 可以在服务器重启后用 `omp --resume=<session>` 恢复 OMP 窗格。
|
||||
|
||||
|
|
|
|||
|
|
@ -62,6 +62,9 @@ command = ["npm", "ci"]
|
|||
command = ["npm", "run", "build"]
|
||||
platforms = ["linux", "macos"]
|
||||
|
||||
[[startup]]
|
||||
command = ["node", "dist/restore.js"]
|
||||
|
||||
[[actions]]
|
||||
id = "apply"
|
||||
title = "Apply layout"
|
||||
|
|
@ -97,9 +100,9 @@ ASCII 字母、数字、冒号、下划线和连字符,但不能用点。每种
|
|||
`plugin.id.action` 的形式。
|
||||
|
||||
用 `platforms = ["linux", "macos", "windows"]` 声明插件可以运行的平台。
|
||||
构建命令、动作、事件钩子、窗格和链接处理器也可以声明自己的 `platforms`;
|
||||
条目级的 platforms 覆盖顶层列表。没有顶层 `platforms` 的本地插件在链接
|
||||
时会给出警告。
|
||||
构建命令、启动钩子、动作、事件钩子、窗格和链接处理器也可以声明自己的
|
||||
`platforms`;条目级的 platforms 覆盖顶层列表。没有顶层 `platforms` 的本地
|
||||
插件在链接时会给出警告。
|
||||
|
||||
`command` 的值是 argv 数组。Herdr 不会通过 shell 运行它们,所以除非你的
|
||||
命令自己启动 shell,否则没有 shell 展开。语言相关的行为放到你的脚本或
|
||||
|
|
@ -174,8 +177,12 @@ herdr plugin log list --plugin example.layout
|
|||
`plugin install` 只接受 GitHub 简写,比如 `owner/repo/subdir`。它用 `git`
|
||||
克隆,在交互式终端展示预览,运行受支持的构建命令,然后把检出保存到
|
||||
Herdr 管理的插件数据下并注册。非交互式安装用 `--yes`。重新安装 GitHub
|
||||
管理的插件会替换该托管检出。不允许覆盖安装到本地链接的插件之上;请先
|
||||
unlink 或 uninstall 本地插件。`plugin install` 和 `plugin link` 会创建
|
||||
管理的插件会替换该托管检出。已安装和已链接的插件及其启用状态对当前用户
|
||||
全局生效,可在所有 Herdr 会话中使用。即使 Herdr 服务器没有运行,也可以通过
|
||||
`plugin install` 和 `plugin link` 注册插件。仅安装在 Herdr 0.7.3 命名会话中的
|
||||
插件必须重新 install 或 link;现有的插件配置和状态会保留。
|
||||
不允许覆盖安装到本地链接的插件之上;请先 unlink 或 uninstall 本地插件。
|
||||
`plugin install` 和 `plugin link` 会创建
|
||||
插件的配置和状态目录,`plugin config-dir <id>` 打印配置目录,方便安装
|
||||
文档和 shell 脚本使用。
|
||||
|
||||
|
|
@ -203,6 +210,20 @@ Herdr socket 环境变量。插件作者应在文档中说明所需的系统工
|
|||
`cargo`、`npm`、`bun` 或 `lua`;Herdr 报告构建失败,但不会安装缺失的
|
||||
工具链。
|
||||
|
||||
## 启动钩子
|
||||
|
||||
Herdr 恢复会话且 API socket 就绪后,会为每个已启用插件运行一次
|
||||
`[[startup]]` 命令。实时交接由新服务器接管时会再次运行,但客户端连接、
|
||||
配置重载以及插件 link 或 enable 时不会运行。Herdr 异步启动这些命令,并在
|
||||
普通插件命令日志中记录完成情况。启动钩子失败不会停止服务器。
|
||||
|
||||
启动钩子是一次性初始化命令,不是受监督的守护进程。钩子应恢复插件自己的
|
||||
状态、调用所需的 Herdr API,然后退出。例如,插件可以把声明式 Agent 视图保存到
|
||||
`HERDR_PLUGIN_STATE_DIR`,再由启动钩子读取并重新应用。
|
||||
|
||||
启动钩子会收到普通运行时插件环境和 `HERDR_PLUGIN_EVENT=startup`。安装预览会
|
||||
列出所有启动命令,让用户检查将自动运行的代码。
|
||||
|
||||
## 命令与环境
|
||||
|
||||
运行时命令以插件目录为工作目录执行。Herdr 注入 `HERDR_SOCKET_PATH`、
|
||||
|
|
@ -210,7 +231,8 @@ Herdr socket 环境变量。插件作者应在文档中说明所需的系统工
|
|||
`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、
|
||||
`HERDR_PLUGIN_CONTEXT_JSON`,以及可用时的 `HERDR_WORKSPACE_ID`、
|
||||
`HERDR_TAB_ID` 和 `HERDR_PANE_ID`。动作命令还会收到
|
||||
`HERDR_PLUGIN_ACTION_ID`;事件钩子收到 `HERDR_PLUGIN_EVENT` 和
|
||||
`HERDR_PLUGIN_ACTION_ID`;启动钩子和事件钩子收到 `HERDR_PLUGIN_EVENT`
|
||||
（启动钩子中的值为 `startup`）,事件钩子还会收到
|
||||
`HERDR_PLUGIN_EVENT_JSON`;窗格命令收到 `HERDR_PLUGIN_ENTRYPOINT_ID`。
|
||||
|
||||
`HERDR_PLUGIN_ROOT` 是已安装或已链接的插件目录。不要把用户凭据或持久
|
||||
|
|
|
|||
|
|
@ -93,6 +93,8 @@ Herdr 只会恢复那些通过当前官方 Herdr 集成上报了原生会话引
|
|||
|
||||
这与快照恢复、窗格历史回放和智能体原生会话恢复不同。交接尝试让当前进程活下去,其他路径则是在旧服务器已经停止之后重建状态。
|
||||
|
||||
交接保护的是由服务器拥有的长期会话状态:窗格 PTY 和进程、智能体身份与持久元数据,以及替换服务器所需的插件/会话状态。它不会跨替换边界保留临时协调状态。进行中的 CLI 或 API 请求、等待、订阅流、客户端套接字和窗格间消息可能会中断;客户端应重新连接并重试。
|
||||
|
||||
实时交接是实验性功能,需要主动开启:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ socket API 可以:
|
|||
- 创建、列出、聚焦、重命名和关闭工作区
|
||||
- 创建、列出、聚焦、重命名和关闭标签页
|
||||
- 列出、检查、分割、交换、聚焦、调整、重命名、读取、关闭窗格并向其发送输入
|
||||
- 通过 CLI 辅助命令列出、检查、读取、发送、重命名、聚焦、启动和附加智能体
|
||||
- 通过 CLI 辅助命令列出、检查、读取、提示、等待、重命名、聚焦、启动和附加智能体
|
||||
- 从钩子和插件上报自定义智能体状态
|
||||
- 订阅事件并等待输出或状态变化
|
||||
- 安装和卸载内置集成
|
||||
|
|
@ -77,7 +77,7 @@ herdr pane split w1:p1 --direction right --ratio 0.333
|
|||
等待智能体:
|
||||
|
||||
```bash
|
||||
herdr wait agent-status w1:p1 --status done
|
||||
herdr agent wait w1:p1 --until done
|
||||
```
|
||||
|
||||
读取窗格输出:
|
||||
|
|
@ -102,12 +102,12 @@ herdr pane read w1:p2 --source recent --lines 50
|
|||
| 窗格 | `pane.split`、`pane.swap`、`pane.move`、`pane.zoom`、`pane.layout`、`pane.process_info`、`pane.neighbor`、`pane.edges`、`pane.focus_direction`、`pane.resize`、`pane.list`、`pane.current`、`pane.get`、`pane.rename`、`pane.send_text`、`pane.send_keys`、`pane.send_input`、`pane.read`、`pane.graphics.info`、`pane.graphics.set`、`pane.graphics.clear`、`pane.graphics.stream`、`pane.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` |
|
||||
| 弹窗 | `popup.close` |
|
||||
| 布局 | `layout.export`、`layout.apply`、`layout.set_split_ratio` |
|
||||
| 智能体 | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send`、`agent.rename`、`agent.focus`、`agent.start` |
|
||||
| 智能体 | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send_keys`、`agent.prompt`、`agent.wait`、`agent.rename`、`agent.focus`、`agent.start` |
|
||||
| 事件 | `events.subscribe`、`events.wait` |
|
||||
| 集成 | `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` |
|
||||
|
||||
一些 CLI 命令是这些方法的便捷包装。比如 `herdr agent wait` 先解析智能体目标,然后订阅窗格智能体状态事件。
|
||||
`agent.wait` 由服务器拥有并由事件驱动。它会固定到已解析的窗格占用者,因此替换后的智能体不能满足该等待。`agent.prompt` 接受可选的 `wait` 对象,其中包含 `until` 和 `timeout_ms`;这样可在一个请求中提交提示并开始等待,避免两个独立调用之间的竞态。
|
||||
|
||||
`session.snapshot` 为维护本地运行时缓存的客户端返回一次性引导快照。响应包含版本/协议元数据、当前聚焦的工作区/标签页/窗格 id、工作区记录、标签页记录、窗格记录、标签页布局快照和智能体记录。它不是订阅;读取后应订阅资源事件,并根据事件更新本地缓存。重新连接后或本地缓存可能已过期时,再次调用 `session.snapshot`。工作区记录也包含关联 worktree 的来源信息。完整的仓库 worktree 发现仍使用 `worktree.list`。
|
||||
|
||||
|
|
@ -297,6 +297,76 @@ Worktree 方法把 Git 检出作为 Herdr 工作区管理。`worktree.create`
|
|||
|
||||
Worktree 命令也发出生命周期事件。`worktree.create` 发出 `workspace.created`、`tab.created`、`pane.created` 和 `worktree.created`。`worktree.open` 发出 `worktree.opened`,并在打开新的 Herdr 工作区时同时发出工作区/标签页/窗格创建事件。`worktree.remove` 发出 `worktree.removed`;如果关联的工作区仍然打开,还会发出 `workspace.closed`。
|
||||
|
||||
## 智能体视图查询
|
||||
|
||||
`agent.view.set` 为内置 Agents 视图设置一个临时的声明式投影。智能体信息或当前
|
||||
UI 上下文变化时,该投影会重新求值。它控制展开和折叠的侧边栏、移动端 Agents
|
||||
列表、鼠标目标、编号聚焦以及上一个/下一个智能体的导航顺序。它不会改变
|
||||
`agent.list`、通知、检测或全局待处理计数。
|
||||
|
||||
下面的示例显示当前呈现的 Space 中的智能体,以及其他位置需要处理的智能体,
|
||||
然后按待处理优先级和最近状态转换排序:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "view_set",
|
||||
"method": "agent.view.set",
|
||||
"params": {
|
||||
"source": "plugin:example.agent-views",
|
||||
"label": "focus",
|
||||
"filter": {
|
||||
"op": "any",
|
||||
"filters": [
|
||||
{
|
||||
"op": "eq",
|
||||
"field": "workspace_id",
|
||||
"value": {"context": "current_workspace_id"}
|
||||
},
|
||||
{
|
||||
"op": "in",
|
||||
"field": "status",
|
||||
"values": ["blocked", "done"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"sort": [
|
||||
{"field": "attention", "order": "desc"},
|
||||
{"field": "state_change_seq", "order": "desc"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
过滤节点的 `op` 可以是 `all`、`any`、`not`、`eq`、`in` 或 `exists`。内置
|
||||
过滤字段是 `status`、`workspace_id`、`tab_id`、`pane_id`、`agent`、`seen`
|
||||
和 `state_change_seq`。要过滤插件上报的窗格元数据,使用 `{"token":"name"}`
|
||||
作为字段。值可以是字符串、布尔值、无符号整数或上下文对象。上下文值包括
|
||||
`current_workspace_id` 和 `current_tab_id`,并且只能与对应的 ID 字段比较。
|
||||
有效 status 值为 `idle`、`working`、`blocked`、`done` 和 `unknown`;`done`
|
||||
表示 idle 且尚未查看。
|
||||
|
||||
排序字段包括 `workspace_order`、`tab_order`、`pane_order`、`attention`、
|
||||
`status`、`agent`、`seen`、`state_change_seq` 或 `{"token":"name"}`。排序是
|
||||
稳定的,按声明顺序求值,并接受 `asc` 或 `desc`。缺失值排在存在值之后。省略
|
||||
`sort` 时,现有 `ui.agent_panel_sort` 策略继续生效。自定义排序会临时替换该
|
||||
策略,但不会重写配置。
|
||||
|
||||
`source` 标识所有者。插件使用 `plugin:<HERDR_PLUGIN_ID>`;当所属插件不存在
|
||||
或被禁用时,Herdr 会拒绝设置。其他调用方可以使用自己的非 `plugin:` source。
|
||||
设置成功会原子替换之前的视图。该视图会持续到被 clear、被替换、所属插件被
|
||||
disable、unlink 或 uninstall,或者服务器退出。需要持久行为的插件应把查询保存到
|
||||
`HERDR_PLUGIN_STATE_DIR`,并从 `[[startup]]` 钩子重新应用。
|
||||
|
||||
可以无条件 clear,也可以只在指定 source 仍拥有视图时 clear:
|
||||
|
||||
```json
|
||||
{"id":"view_clear","method":"agent.view.clear","params":{}}
|
||||
{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}
|
||||
```
|
||||
|
||||
source 不匹配时,活动视图保持不变。set 和 clear 响应使用
|
||||
`type: "agent_view"`,并报告 `active`、`source` 和可选的 `label`。
|
||||
|
||||
## 插件 API
|
||||
|
||||
插件 API 是面向可执行工作流工具的早期宿主面。插件是带 `herdr-plugin.toml` 清单的包。清单声明可分享的动作、事件钩子、终端窗格入口点和链接处理器。动作和窗格仅限清单声明;运行时动作注册和运行时 argv 窗格创建不在 v1 范围内。
|
||||
|
|
@ -589,8 +659,8 @@ herdr pane read w1:p1 --source detection
|
|||
用等待来协调智能体和脚本。
|
||||
|
||||
```bash
|
||||
herdr wait agent-status w1:p1 --status done
|
||||
herdr wait agent-status w1:p1 --status blocked
|
||||
herdr agent wait w1:p1 --until done
|
||||
herdr agent wait w1:p1 --until blocked
|
||||
```
|
||||
|
||||
智能体等待观察的是语义状态,不是任意命令的完成。
|
||||
|
|
|
|||
|
|
@ -565,6 +565,12 @@
|
|||
"default": "36",
|
||||
"description": "Maximum sidebar width (columns) when expanded."
|
||||
},
|
||||
{
|
||||
"key": "ui.sidebar_start_collapsed",
|
||||
"type": "boolean",
|
||||
"default": "false",
|
||||
"description": "Start Herdr with the sidebar collapsed. Changes take effect on the next launch."
|
||||
},
|
||||
{
|
||||
"key": "ui.sidebar_collapsed_mode",
|
||||
"type": "enum",
|
||||
|
|
@ -634,6 +640,12 @@
|
|||
"default": "true",
|
||||
"description": "Ask for a tab name before creating a new tab."
|
||||
},
|
||||
{
|
||||
"key": "ui.prompt_new_workspace_name",
|
||||
"type": "boolean",
|
||||
"default": "false",
|
||||
"description": "Ask for a workspace name before interactive TUI creation."
|
||||
},
|
||||
{
|
||||
"key": "ui.pane_borders",
|
||||
"type": "boolean",
|
||||
|
|
@ -678,7 +690,7 @@
|
|||
"key": "ui.sidebar.agents.rows",
|
||||
"type": "list of token rows",
|
||||
"default": "[[\"state_icon\", \"workspace\", \"tab\"], [\"agent\"]]",
|
||||
"description": "Default expanded Agent sidebar layout. Supports built-in tokens and $name metadata tokens; at most 16 rows and 16 tokens per row."
|
||||
"description": "Default expanded Agent sidebar layout. Entries may be token strings or inline { token, fg, bold, dim } style tables. Supports built-in and $name metadata tokens; at most 16 rows and 16 tokens per row."
|
||||
},
|
||||
{
|
||||
"key": "ui.sidebar.agents.rows_by_agent",
|
||||
|
|
@ -696,7 +708,7 @@
|
|||
"key": "ui.sidebar.spaces.rows",
|
||||
"type": "list of token rows",
|
||||
"default": "[[\"state_icon\", \"workspace\"], [\"branch\", \"git_status\"]]",
|
||||
"description": "Expanded Space sidebar layout. Supports built-in tokens and $name metadata tokens; at most 16 rows and 16 tokens per row."
|
||||
"description": "Expanded Space sidebar layout. Entries may be token strings or inline { token, fg, bold, dim } style tables. Supports built-in and $name metadata tokens; at most 16 rows and 16 tokens per row."
|
||||
},
|
||||
{
|
||||
"key": "ui.accent",
|
||||
|
|
|
|||
Loading…
Reference in New Issue