Ogulcan Celik
parent
e584f93f36
commit
5b2fce600f
35
CHANGELOG.md
35
CHANGELOG.md
|
|
@ -2,6 +2,41 @@
|
|||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
- Added a compact collapse control to the expanded sidebar so mouse users can collapse and expand the sidebar from visible controls. (#278, #291, thanks @turgaybulut)
|
||||
- Added an opt-in preview update channel with `herdr channel set preview`, `[update].channel`, automated preview manifests, and GitHub prerelease publishing for users who want fixes before stable releases as Herdr transitions toward less frequent, more stable releases.
|
||||
- Added a remote SSH bridge keepalive fallback. `herdr --remote` now generates a temporary SSH config that includes the user's SSH config first, then adds `ServerAliveInterval` and `ServerAliveCountMax` only when the user has not already configured keepalives. Set `[remote].manage_ssh_config = false` to disable this. (#354, #355, thanks @SunskyXH)
|
||||
- Added `ui.right_click_passthrough_modifier` so a configured modifier such as `ctrl` can forward right-click hold and drag gestures to mouse-reporting pane apps while normal right-click still opens Herdr's pane menu. (#148)
|
||||
- Added Kilo Code CLI automatic detection for idle, working, and blocked terminal states. (#270)
|
||||
- Added `herdr integration install copilot` for GitHub Copilot CLI hooks that report prompt, tool, post-approval progress, permission, `ask_user`, `exit_plan_mode`, idle, session-exit state, and session ids through Herdr's socket API. When native agent session restore is enabled, Herdr can resume Copilot panes with `copilot --resume=<id>`. (#232, #386, thanks @LaneBirmingham)
|
||||
|
||||
### Changed
|
||||
- Native agent session restore is now enabled by default for supported panes with current official integrations. Set `[session] resume_agents_on_restore = false` to disable it.
|
||||
- Claude Code, Codex, and OpenCode integrations now report session identity only. Native state for those agents comes from Herdr's screen detection, while Pi, OMP, GitHub Copilot CLI, Hermes Agent, Qoder CLI, and custom socket integrations can still report state.
|
||||
|
||||
### Fixed
|
||||
- Large long-running sessions no longer hit the frame-streaming crash fixed by the vendored libghostty-vt update. (#276)
|
||||
- Copy mode now preserves linewise selection after `shift+v` while moving the cursor. (#360, #389, thanks @reobin)
|
||||
- Leaving copy mode now restores the previous scroll position, or returns to the bottom when copy mode started at the bottom. (#398, #410, thanks @reobin)
|
||||
- Git branch labels now resolve correctly in repositories that use Git's reftable ref format instead of showing `.invalid`. (#384, #423, thanks @LaneBirmingham)
|
||||
- The official Nix flake now builds on macOS by providing Darwin SDK discovery helpers and Darwin cctools to the vendored libghostty-vt build. (#405, #407, thanks @DeevsDeevs)
|
||||
- Commands launched after `--`, such as `herdr agent start ... -- opencode --session <id>`, now preserve child argv flags instead of parsing them as Herdr flags. (#383)
|
||||
- Pane apps that request any-motion mouse tracking now receive hover/move events, making Textual-style TUI mouse interaction more reliable inside Herdr. (#419)
|
||||
- Claude Code background-agent wait text in scrollback no longer keeps an idle pane marked working after the background agent has completed.
|
||||
- Claude Code and Codex transcript or expanded-detail viewers no longer publish a false idle state while the pane is still showing active agent status.
|
||||
- Claude Code question prompts that use the arrow-glyph selector are now detected as blocked.
|
||||
- Kiro sub-agent tool approval prompts are now detected as blocked instead of working. (#388)
|
||||
- Shift-letter prefix bindings such as `prefix+shift+n` now work in legacy SSH terminal sessions that send uppercase letters without separate Shift metadata. (#312)
|
||||
- Idle panes now avoid repeated full foreground-process scans, reducing idle CPU on sessions with many panes. (#439)
|
||||
- Restored native agent sessions now resume across background workspaces and tabs after the first client provides terminal context instead of waiting until each pane is focused.
|
||||
- Pane input no longer waits behind the PTY actor's idle read poll, restoring responsive typing at quiet shell prompts. (#379)
|
||||
- Pane apps that query OSC 4 ANSI palette colors now receive the active terminal palette response, so OpenCode and similar TUIs can enable system-theme behavior inside Herdr. (#387)
|
||||
- Pane apps that query terminal capabilities with XTGETTCAP now receive supported capability responses, improving feature detection in Neovim and similar terminal apps. (#393)
|
||||
- Pane text selection now derives its highlight colors from the host terminal or active Herdr palette instead of forcing the theme's blue accent. (#298)
|
||||
- `herdr channel set preview` and `herdr channel set stable` now update direct installs from the selected channel immediately, reject preview on Homebrew and Nix installs before changing config, and show package-manager guidance for managed installs.
|
||||
- Plain `herdr update` and remote binary replacement now ask before stopping running sessions, avoid protocol-heavy prompt text, and leave the current install untouched when the user chooses not to stop active pane processes. Explicit `--handoff` update flows try live handoff without a second handoff prompt.
|
||||
- Remote bootstrap now uses the remote shell only for PATH discovery and runs internal probes through `/bin/sh`, so `herdr --remote` can detect existing installs when the remote login shell is fish. (#396)
|
||||
|
||||
## [0.6.6] - 2026-05-31
|
||||
|
||||
### Added
|
||||
|
|
|
|||
32
README.md
32
README.md
|
|
@ -53,11 +53,11 @@ Press `ctrl+b q` to detach the client. The server and pane processes keep runnin
|
|||
|
||||
**Copy.** Herdr copies pane text, not the sidebar. Drag-select inside a pane, double-click a word or token, or press `prefix+[` for keyboard copy mode. In copy mode, move with `h/j/k/l`, `w/b/e`, and `{`/`}`, start selection with `v` or Space, copy with `y` or Enter, and leave with `q` or Esc. In PuTTY and some SSH terminals, hold `Shift` while dragging to use the terminal's own selection, and `Shift` + right click to paste.
|
||||
|
||||
**Update and restore.** `herdr update` installs a new binary, but a running server keeps using the old process until it is stopped or handed off. Stop the old server to use the new version. Stopping exits pane processes. Run `herdr server stop`, then run `herdr` again for the default session. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again. `herdr update --handoff` is experimental and tries to move live panes, including foreground processes such as dev servers, from the old server to the new one. If `[session] resume_agents_on_restore = true` is enabled and current official integrations are installed, supported agent panes can restart from their native agent sessions after a server restart or update.
|
||||
**Update and restore.** `herdr update` installs a new binary, but a running server keeps using the old process until it is stopped or handed off. Stop the old server to use the new version. Stopping exits pane processes. Run `herdr server stop`, then run `herdr` again for the default session. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again. `herdr update --handoff` is experimental and tries to move live panes, including foreground processes such as dev servers, from the old server to the new one. With current official integrations installed, supported agent panes can restart from their native agent sessions after a server restart or update.
|
||||
|
||||
**Keybindings.** Herdr uses explicit keybinding strings. `prefix+n` means press the configured prefix, then `n`. `ctrl+alt+n`, `cmd+k`, `alt+1`, and function-key chords are direct terminal-mode shortcuts and do not need the prefix. Plain direct printable keys such as `n` steal normal typing, so use `prefix+n` unless you intentionally want a modifier-gated direct binding.
|
||||
|
||||
**Agent awareness.** The sidebar shows blocked, working, done, and idle states. Detection works with process names and terminal output by default. Official integrations make state reporting and native agent session restore more reliable, but Herdr still works as a terminal multiplexer without them.
|
||||
**Agent awareness.** The sidebar shows blocked, working, done, and idle states. Detection works with process names and terminal output by default. Official integrations can add native session identity for restore, semantic state reports, or both.
|
||||
|
||||
## update
|
||||
|
||||
|
|
@ -67,7 +67,23 @@ Herdr notifies you when a new version is available. Run manually:
|
|||
herdr update
|
||||
```
|
||||
|
||||
`herdr update` is for installs managed by Herdr's own installer. Homebrew and Nix installs update through `brew upgrade herdr` or your Nix workflow, then use the same stop-and-run-again flow if a session is still running the old server. See [install docs](https://herdr.dev/docs/install/) and [session state docs](https://herdr.dev/docs/session-state/) for the full update, restart, restore, and handoff matrix.
|
||||
`herdr update` is for installs managed by Herdr's own installer. Homebrew and Nix installs update through `brew upgrade herdr` or your Nix workflow, then use the same stop-and-run-again flow if a session is still running the old server. Direct installs can opt into development preview builds with `herdr channel set preview` and return to stable with `herdr channel set stable`. See [install docs](https://herdr.dev/docs/install/) and [session state docs](https://herdr.dev/docs/session-state/) for the full update, restart, restore, and handoff matrix.
|
||||
|
||||
Herdr uses the stable update channel by default. To test preview builds from `master` before the next stable release:
|
||||
|
||||
```bash
|
||||
herdr channel set preview
|
||||
```
|
||||
|
||||
To return to stable:
|
||||
|
||||
```bash
|
||||
herdr channel set stable
|
||||
```
|
||||
|
||||
For direct installs, changing channels also checks that channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
|
||||
|
||||
Preview is only for direct installs managed by Herdr's updater. Homebrew and Nix stay on stable and update through their package managers.
|
||||
|
||||
## how it compares
|
||||
|
||||
|
|
@ -101,6 +117,8 @@ herdr --remote workbox
|
|||
herdr --remote ssh://you@yourserver:2222
|
||||
```
|
||||
|
||||
Remote attach adds fallback SSH keepalives by default while preserving your own SSH config. Set `[remote].manage_ssh_config = false` to use plain `ssh`.
|
||||
|
||||
Direct attach connects your current terminal to one server-owned terminal:
|
||||
|
||||
```bash
|
||||
|
|
@ -121,7 +139,7 @@ states:
|
|||
- 🔵 **done** — work finished, you have not looked at it yet
|
||||
- 🟢 **idle** — done and seen
|
||||
|
||||
detection works by reading foreground process and terminal output. zero config, no hooks required. for agents that expose hooks, the socket api integration gives more robust state reporting.
|
||||
detection works by reading foreground process and terminal output. zero config, no hooks required. official claude code, codex, and opencode integrations provide session restore identity; pi, omp, github copilot cli, hermes, qodercli, and custom socket integrations can report their own state.
|
||||
|
||||
## lives in your terminal
|
||||
|
||||
|
|
@ -154,6 +172,7 @@ automatic detection works out of the box. process name matching plus terminal ou
|
|||
| [opencode](https://github.com/anomalyco/opencode) | ✓ | ✓ | ✓ |
|
||||
| [grok cli](https://x.ai/grok) | ✓ | ✓ | ✓ |
|
||||
| [hermes agent](https://github.com/NousResearch/hermes-agent) | ✓ | ✓ | ✓ |
|
||||
| [kilo code cli](https://kilo.ai/) | ✓ | ✓ | ✓ |
|
||||
| cursor agent | ✓ | ✓ | ✓ |
|
||||
| antigravity cli | ✓ | ✓ | ✓ |
|
||||
| kimi code cli | ✓ | ✓ | ✓ |
|
||||
|
|
@ -167,13 +186,14 @@ for agents outside the built-in list, herdr still works as a terminal multiplexe
|
|||
|
||||
### direct integrations
|
||||
|
||||
the built-in pi, omp, claude code, codex, opencode, hermes, and qodercli integrations forward semantic state to herdr over the socket api. install with:
|
||||
official integrations have two roles. claude code, codex, and opencode report session identity for native restore, while their state still comes from screen detection. pi, github copilot cli, and hermes report both semantic state and session identity. omp and qodercli report semantic state without native session restore. install with:
|
||||
|
||||
```bash
|
||||
herdr integration install pi
|
||||
herdr integration install omp
|
||||
herdr integration install claude
|
||||
herdr integration install codex
|
||||
herdr integration install copilot
|
||||
herdr integration install opencode
|
||||
herdr integration install hermes
|
||||
herdr integration install qodercli
|
||||
|
|
@ -222,7 +242,7 @@ In-app settings cover theme, sound, and toast preferences. Herdr writes logs und
|
|||
- [install](https://herdr.dev/docs/install/) — install, update, Homebrew, and Nix
|
||||
- [session state](https://herdr.dev/docs/session-state/) — detach, restart restore, agent restore, and live handoff
|
||||
- [configuration](https://herdr.dev/docs/configuration/) — keybindings, themes, notifications, environment variables
|
||||
- [integrations](https://herdr.dev/docs/integrations/) — pi, omp, claude code, codex, opencode, hermes, qodercli integrations
|
||||
- [integrations](https://herdr.dev/docs/integrations/) — pi, omp, claude code, codex, github copilot cli, opencode, hermes, qodercli integrations
|
||||
- [`SKILL.md`](./SKILL.md) — reusable agent skill
|
||||
- [socket api](https://herdr.dev/docs/socket-api/) — socket protocol and cli reference
|
||||
|
||||
|
|
|
|||
|
|
@ -3,23 +3,37 @@
|
|||
## Unreleased
|
||||
|
||||
### Added
|
||||
- Added an opt-in preview update channel with `herdr channel set preview`, automated preview manifests, and GitHub prerelease publishing for users who want fixes before stable releases.
|
||||
- Added a compact collapse control to the expanded sidebar so mouse users can collapse and expand the sidebar from visible controls. (#278, #291, thanks @turgaybulut)
|
||||
- Added an opt-in preview update channel with `herdr channel set preview`, `[update].channel`, automated preview manifests, and GitHub prerelease publishing for users who want fixes before stable releases as Herdr transitions toward less frequent, more stable releases.
|
||||
- Added a remote SSH bridge keepalive fallback. `herdr --remote` now generates a temporary SSH config that includes the user's SSH config first, then adds `ServerAliveInterval` and `ServerAliveCountMax` only when the user has not already configured keepalives. Set `[remote].manage_ssh_config = false` to disable this. (#354, #355, thanks @SunskyXH)
|
||||
- Added `ui.right_click_passthrough_modifier` so a configured modifier such as `ctrl` can forward right-click hold and drag gestures to mouse-reporting pane apps while normal right-click still opens Herdr's pane menu. (#148)
|
||||
- Added Kilo Code CLI automatic detection for idle, working, and blocked terminal states. (#270)
|
||||
- Added `herdr integration install copilot` for GitHub Copilot CLI hooks that report prompt, tool, post-approval progress, permission, `ask_user`, `exit_plan_mode`, idle, session-exit state, and session ids through Herdr's socket API. When `[session] resume_agents_on_restore = true` is enabled, Herdr can resume Copilot panes with `copilot --resume=<id>`.
|
||||
- Added `herdr integration install copilot` for GitHub Copilot CLI hooks that report prompt, tool, post-approval progress, permission, `ask_user`, `exit_plan_mode`, idle, session-exit state, and session ids through Herdr's socket API. When native agent session restore is enabled, Herdr can resume Copilot panes with `copilot --resume=<id>`. (#232, #386, thanks @LaneBirmingham)
|
||||
|
||||
### Changed
|
||||
- Native agent session restore is now enabled by default for supported panes with current official integrations. Set `[session] resume_agents_on_restore = false` to disable it.
|
||||
- Claude Code, Codex, and OpenCode integrations now report session identity only. Native state for those agents comes from Herdr's screen detection, while Pi, OMP, GitHub Copilot CLI, Hermes Agent, Qoder CLI, and custom socket integrations can still report state.
|
||||
|
||||
### Fixed
|
||||
- Large long-running sessions no longer hit the frame-streaming crash fixed by the vendored libghostty-vt update. (#276)
|
||||
- Copy mode now preserves linewise selection after `shift+v` while moving the cursor. (#360, #389, thanks @reobin)
|
||||
- Leaving copy mode now restores the previous scroll position, or returns to the bottom when copy mode started at the bottom. (#398, #410, thanks @reobin)
|
||||
- Git branch labels now resolve correctly in repositories that use Git's reftable ref format instead of showing `.invalid`. (#384, #423, thanks @LaneBirmingham)
|
||||
- The official Nix flake now builds on macOS by providing Darwin SDK discovery helpers and Darwin cctools to the vendored libghostty-vt build. (#405, #407, thanks @DeevsDeevs)
|
||||
- Commands launched after `--`, such as `herdr agent start ... -- opencode --session <id>`, now preserve child argv flags instead of parsing them as Herdr flags. (#383)
|
||||
- Pane apps that request any-motion mouse tracking now receive hover/move events, making Textual-style TUI mouse interaction more reliable inside Herdr. (#419)
|
||||
- Claude Code background-agent wait text in scrollback no longer keeps an idle pane marked working after the background agent has completed.
|
||||
- Claude Code and Codex transcript or expanded-detail viewers no longer publish a false idle state while the pane is still showing active agent status.
|
||||
- Claude Code question prompts that use the arrow-glyph selector are now detected as blocked.
|
||||
- Kiro sub-agent tool approval prompts are now detected as blocked instead of working. (#388)
|
||||
- Shift-letter prefix bindings such as `prefix+shift+n` now work in legacy SSH terminal sessions that send uppercase letters without separate Shift metadata. (#312)
|
||||
- Idle panes now avoid repeated full foreground-process scans, reducing idle CPU on sessions with many panes. (#439)
|
||||
- Restored native agent sessions now resume across background workspaces and tabs after the first client provides terminal context instead of waiting until each pane is focused.
|
||||
- Pane input no longer waits behind the PTY actor's idle read poll, restoring responsive typing at quiet shell prompts. (#379)
|
||||
- Pane apps that query OSC 4 ANSI palette colors now receive the active terminal palette response, so OpenCode and similar TUIs can enable system-theme behavior inside Herdr. (#387)
|
||||
- Pane apps that query terminal capabilities with XTGETTCAP now receive supported capability responses, improving feature detection in Neovim and similar terminal apps. (#393)
|
||||
- Pane text selection now derives its highlight colors from the host terminal or active Herdr palette instead of forcing the theme's blue accent. (#298)
|
||||
- `herdr channel set preview` and `herdr channel set stable` now update direct installs from the selected channel immediately, reject preview on Homebrew and Nix installs before changing config, and show package-manager guidance for managed installs.
|
||||
- Plain `herdr update` and remote binary replacement now ask before stopping running sessions, avoid protocol-heavy prompt text, and leave the current install untouched when the user chooses not to stop active pane processes. Explicit `--handoff` update flows try live handoff without a second handoff prompt.
|
||||
- Remote bootstrap now uses the remote shell only for PATH discovery and runs internal probes through `/bin/sh`, so `herdr --remote` can detect existing installs when the remote login shell is fish. (#396)
|
||||
|
||||
|
|
|
|||
|
|
@ -117,6 +117,8 @@ herdr --remote workbox
|
|||
herdr --remote ssh://you@yourserver:2222
|
||||
```
|
||||
|
||||
Remote attach adds fallback SSH keepalives by default while preserving your own SSH config. Set `[remote].manage_ssh_config = false` to use plain `ssh`.
|
||||
|
||||
Direct attach connects your current terminal to one server-owned terminal:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -33,6 +33,17 @@ Herdr shows first-run setup when `onboarding` is missing or true. Continuing fro
|
|||
onboarding = false
|
||||
```
|
||||
|
||||
## Update channel
|
||||
|
||||
Direct installs use the stable update channel by default.
|
||||
|
||||
```toml
|
||||
[update]
|
||||
channel = "stable"
|
||||
```
|
||||
|
||||
Set `channel = "preview"` to make `herdr update` install preview builds from the current development branch. Homebrew and Nix installs ignore the preview channel and update through their package managers.
|
||||
|
||||
## Reload config
|
||||
|
||||
Reload a running server after editing `config.toml`:
|
||||
|
|
@ -91,6 +102,17 @@ Grouped worktrees still behave like normal Herdr workspaces: they can be focused
|
|||
|
||||
Deleting a worktree checkout is explicit. Use `Delete worktree checkout...` on a grouped child workspace to run `git worktree remove`. Herdr first asks Git to remove safely. If Git refuses because the checkout has modified or untracked files, Herdr asks again before running the forced remove. Branches are not deleted.
|
||||
|
||||
## Remote attach
|
||||
|
||||
Remote attach manages its SSH bridge with a temporary keepalive fallback by default.
|
||||
|
||||
```toml
|
||||
[remote]
|
||||
manage_ssh_config = true
|
||||
```
|
||||
|
||||
When enabled, `herdr --remote` writes a private temporary SSH config that includes your `~/.ssh/config` and `/etc/ssh/ssh_config` first, then adds fallback `ServerAliveInterval` and `ServerAliveCountMax` values. Your own SSH keepalive settings win. Set `manage_ssh_config = false` to run the bridge through plain `ssh` without Herdr's generated config.
|
||||
|
||||
## Keybindings
|
||||
|
||||
Herdr has a prefix mode similar to tmux. The default prefix is `ctrl+b`. Keybinding strings are explicit: `prefix+n` means press the configured prefix and then `n`; `ctrl+alt+n` is a direct terminal-mode shortcut.
|
||||
|
|
|
|||
|
|
@ -92,6 +92,8 @@ herdr --remote workbox
|
|||
|
||||
Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks `~/.local/bin/herdr`. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.
|
||||
|
||||
By default, `herdr --remote` runs the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings. Existing user keepalive settings win. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated bridge config.
|
||||
|
||||
By default, remote attach uses the normal restart/stop flow if it needs to replace or restart a running remote server. To opt into experimental live handoff for a supported running remote server, pass `--handoff`:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ Automatic detection works out of the box for common coding agents.
|
|||
| OpenCode | yes | yes | yes |
|
||||
| Grok CLI | yes | yes | yes |
|
||||
| Hermes Agent | yes | yes | yes |
|
||||
| Kilo Code CLI | yes | yes | yes |
|
||||
| Cursor Agent | yes | yes | yes |
|
||||
| Antigravity CLI | yes | yes | yes |
|
||||
| Kimi Code CLI | yes | yes | yes |
|
||||
|
|
@ -36,9 +37,9 @@ Herdr combines three signals:
|
|||
|
||||
1. foreground process detection
|
||||
2. terminal output heuristics
|
||||
3. integration state reports
|
||||
3. integration session identity or state reports
|
||||
|
||||
Process detection tells Herdr which pane owns an agent. Heuristics infer state when no hook is available. Integrations provide the most precise semantic state.
|
||||
Process detection tells Herdr which pane owns an agent. Heuristics infer native agent state from terminal screen snapshots. Claude Code, Codex, and OpenCode integrations provide session identity for restore; Pi, OMP, GitHub Copilot CLI, Hermes Agent, Qoder CLI, and custom socket integrations can report state when they define state outside the native terminal UI.
|
||||
|
||||
## State rollups
|
||||
|
||||
|
|
@ -57,6 +58,7 @@ herdr integration install pi
|
|||
herdr integration install omp
|
||||
herdr integration install claude
|
||||
herdr integration install codex
|
||||
herdr integration install copilot
|
||||
herdr integration install opencode
|
||||
herdr integration install hermes
|
||||
herdr integration install qodercli
|
||||
|
|
|
|||
|
|
@ -17,8 +17,11 @@ herdr --remote workbox --remote-keybindings server
|
|||
herdr --remote workbox --handoff
|
||||
herdr --no-session # single-process escape hatch
|
||||
herdr --default-config # print default config
|
||||
herdr update # download and install the latest version
|
||||
herdr update # download and install from the configured channel
|
||||
herdr update --handoff # opt into live handoff for supported running servers
|
||||
herdr channel show # print stable or preview
|
||||
herdr channel set preview # opt into preview builds
|
||||
herdr channel set stable # return to stable releases
|
||||
herdr --version # print version
|
||||
```
|
||||
|
||||
|
|
@ -207,6 +210,7 @@ herdr integration install pi
|
|||
herdr integration install omp
|
||||
herdr integration install claude
|
||||
herdr integration install codex
|
||||
herdr integration install copilot
|
||||
herdr integration install opencode
|
||||
herdr integration install hermes
|
||||
herdr integration install qodercli
|
||||
|
|
@ -214,6 +218,7 @@ herdr integration uninstall pi
|
|||
herdr integration uninstall omp
|
||||
herdr integration uninstall claude
|
||||
herdr integration uninstall codex
|
||||
herdr integration uninstall copilot
|
||||
herdr integration uninstall opencode
|
||||
herdr integration uninstall hermes
|
||||
herdr integration uninstall qodercli
|
||||
|
|
|
|||
|
|
@ -33,6 +33,17 @@ Herdr shows first-run setup when `onboarding` is missing or true. Continuing fro
|
|||
onboarding = false
|
||||
```
|
||||
|
||||
## Update channel
|
||||
|
||||
Direct installs use the stable update channel by default.
|
||||
|
||||
```toml
|
||||
[update]
|
||||
channel = "stable"
|
||||
```
|
||||
|
||||
Set `channel = "preview"` to make `herdr update` install preview builds from the current development branch. Homebrew and Nix installs ignore the preview channel and update through their package managers.
|
||||
|
||||
## Reload config
|
||||
|
||||
Reload a running server after editing `config.toml`:
|
||||
|
|
@ -91,6 +102,17 @@ Grouped worktrees still behave like normal Herdr workspaces: they can be focused
|
|||
|
||||
Deleting a worktree checkout is explicit. Use `Delete worktree checkout...` on a grouped child workspace to run `git worktree remove`. Herdr first asks Git to remove safely. If Git refuses because the checkout has modified or untracked files, Herdr asks again before running the forced remove. Branches are not deleted.
|
||||
|
||||
## Remote attach
|
||||
|
||||
Remote attach manages its SSH bridge with a temporary keepalive fallback by default.
|
||||
|
||||
```toml
|
||||
[remote]
|
||||
manage_ssh_config = true
|
||||
```
|
||||
|
||||
When enabled, `herdr --remote` writes a private temporary SSH config that includes your `~/.ssh/config` and `/etc/ssh/ssh_config` first, then adds fallback `ServerAliveInterval` and `ServerAliveCountMax` values. Your own SSH keepalive settings win. Set `manage_ssh_config = false` to run the bridge through plain `ssh` without Herdr's generated config.
|
||||
|
||||
## Keybindings
|
||||
|
||||
Herdr has a prefix mode similar to tmux. The default prefix is `ctrl+b`. Keybinding strings are explicit: `prefix+n` means press the configured prefix and then `n`; `ctrl+alt+n` is a direct terminal-mode shortcut.
|
||||
|
|
@ -242,6 +264,7 @@ sidebar_min_width = 18
|
|||
sidebar_max_width = 36
|
||||
mobile_width_threshold = 64
|
||||
mouse_capture = true
|
||||
right_click_passthrough_modifier = ""
|
||||
redraw_on_focus_gained = true
|
||||
mouse_scroll_lines = 3
|
||||
confirm_close = true
|
||||
|
|
@ -261,6 +284,8 @@ accent = "cyan"
|
|||
|
||||
Set `mouse_capture = false` if you want your terminal to handle normal clicks, such as command-clicking URLs. With mouse capture enabled, Ctrl-click opens pane links when your terminal sends that modified click to Herdr; use Shift-Ctrl-click on Linux or Shift-Cmd-click on macOS for the terminal-native bypass path.
|
||||
|
||||
Set `right_click_passthrough_modifier = "ctrl"` if you want Ctrl-right-click, hold, and drag gestures inside mouse-reporting pane apps to reach the app instead of opening Herdr's pane menu. The default is empty, which disables this passthrough. Supported modifiers are `ctrl`, `alt`, `cmd`, `super`, `meta`, and `hyper`; `shift` is rejected because many terminals reserve Shift+mouse for their own mouse bypass.
|
||||
|
||||
Set `redraw_on_focus_gained = false` to avoid the visible full-screen refresh when switching back to Herdr. The default is `true` because a full redraw recovers from rare stale or dirty host terminal surfaces.
|
||||
|
||||
Set `mouse_scroll_lines` to change how many pane scrollback lines each mouse wheel notch scrolls. The default is 3. Pane apps that request mouse reporting still receive wheel events directly.
|
||||
|
|
@ -374,10 +399,10 @@ Herdr can restart supported agent panes in their native conversation sessions af
|
|||
|
||||
```toml
|
||||
[session]
|
||||
resume_agents_on_restore = false
|
||||
resume_agents_on_restore = true
|
||||
```
|
||||
|
||||
When enabled, Herdr only resumes panes that reported a native session reference through an official Herdr integration. Supported resume targets are Claude Code, Codex, Pi, Hermes Agent, and OpenCode. Unsupported, missing, invalid, duplicated, or stale session references restore as a normal shell in the saved pane directory.
|
||||
This is enabled by default. Herdr only resumes panes that reported a native session reference through an official Herdr integration. Supported resume targets are Claude Code, Codex, GitHub Copilot CLI, Pi, Hermes Agent, and OpenCode. Unsupported, missing, invalid, duplicated, or stale session references restore as a normal shell in the saved pane directory.
|
||||
|
||||
Session references are stored in the local Herdr session snapshot. They are not shown in normal pane, agent, status, or event output.
|
||||
|
||||
|
|
@ -398,7 +423,7 @@ cjk_ime_cursor_shape = "steady_block"
|
|||
|
||||
When enabled, the cursor stays visible at the focused pane's reported position. If the pane reports no cursor position, the anchor falls back to the pane's top-left so a stable IME hint is always available.
|
||||
|
||||
`cjk_ime_agents` is an optional allow-list. When empty, the reveal applies to any focused pane. When non-empty, the reveal only applies if the focused pane's detected agent matches one of the listed names — useful to enable the reveal only for AI-agent TUIs that paint their own cursor while leaving plain shells untouched. Accepted names: `pi`, `claude`, `codex`, `gemini`, `cursor`, `agy`, `cline`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `qodercli`, and `qoder`. Unknown names are ignored; if the list contains no valid names, the reveal does not apply.
|
||||
`cjk_ime_agents` is an optional allow-list. When empty, the reveal applies to any focused pane. When non-empty, the reveal only applies if the focused pane's detected agent matches one of the listed names — useful to enable the reveal only for AI-agent TUIs that paint their own cursor while leaving plain shells untouched. Accepted names: `pi`, `claude`, `codex`, `gemini`, `cursor`, `agy`, `cline`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `kilo`, `qodercli`, and `qoder`. Unknown names are ignored; if the list contains no valid names, the reveal does not apply.
|
||||
|
||||
`cjk_ime_cursor_shape` controls the DECSCUSR shape rendered for the IME anchor. Accepted values: `block`, `steady_block` (default), `underline`, `steady_underline`, `bar`, `steady_bar`.
|
||||
|
||||
|
|
|
|||
|
|
@ -43,6 +43,22 @@ herdr update
|
|||
|
||||
`herdr update` is for installs managed by Herdr's own installer. Homebrew and Nix installs are updated through those package managers instead.
|
||||
|
||||
Herdr uses the stable update channel by default. To opt into preview builds from `master`, set the channel:
|
||||
|
||||
```bash
|
||||
herdr channel set preview
|
||||
```
|
||||
|
||||
Switch back to stable the same way:
|
||||
|
||||
```bash
|
||||
herdr channel set stable
|
||||
```
|
||||
|
||||
For direct installs, changing channels also checks that channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
|
||||
|
||||
Preview builds are GitHub prereleases published from the current development branch. They are useful when you want fixes before the next stable release, but they can regress. Homebrew and Nix installs do not use the preview channel.
|
||||
|
||||
By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping exits pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
|
||||
|
||||
To opt into experimental live server handoff for supported running sessions, run:
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
title: Integrations
|
||||
description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, OpenCode, Hermes Agent, and Qoder CLI.
|
||||
description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, OpenCode, Hermes Agent, and Qoder CLI.
|
||||
---
|
||||
|
||||
Herdr detects supported agents automatically. Integrations make that detection more precise by reporting semantic state directly to Herdr.
|
||||
Herdr detects supported agents automatically. Official integrations can add native session identity for restore, semantic state reports, or both. Claude Code, Codex, and OpenCode state comes from screen detection even when their session identity integrations are installed.
|
||||
|
||||
Use integrations when you want reliable `working`, `blocked`, `idle`, and `done` state from agent hooks or plugins.
|
||||
Use integrations when you want native agent session restore, direct state reports from Pi/OMP/Copilot/Hermes/Qoder-style hooks or plugins, or both.
|
||||
|
||||
## Install integrations
|
||||
|
||||
|
|
@ -16,6 +16,7 @@ herdr integration install pi
|
|||
herdr integration install omp
|
||||
herdr integration install claude
|
||||
herdr integration install codex
|
||||
herdr integration install copilot
|
||||
herdr integration install opencode
|
||||
herdr integration install hermes
|
||||
herdr integration install qodercli
|
||||
|
|
@ -28,6 +29,7 @@ herdr integration uninstall pi
|
|||
herdr integration uninstall omp
|
||||
herdr integration uninstall claude
|
||||
herdr integration uninstall codex
|
||||
herdr integration uninstall copilot
|
||||
herdr integration uninstall opencode
|
||||
herdr integration uninstall hermes
|
||||
herdr integration uninstall qodercli
|
||||
|
|
@ -40,14 +42,14 @@ Herdr combines three signals:
|
|||
| Signal | Purpose |
|
||||
| --- | --- |
|
||||
| Process detection | Identifies which pane owns which running process. |
|
||||
| Agent integration events | Reports semantic state such as `working` or `blocked`. |
|
||||
| Screen heuristics | Fills gaps when hooks are unavailable or incomplete. |
|
||||
| Screen heuristics | Infers visible native agent state such as `working` or `blocked`. |
|
||||
| Integration events | Reports native session identity, semantic state, or both depending on the integration. |
|
||||
|
||||
Integrations enrich state reporting. They do not replace process detection.
|
||||
Claude Code, Codex, and OpenCode state detection is screen-read first. Their Herdr-owned integrations do not author `idle`, `working`, or `blocked` state. Pi, GitHub Copilot CLI, and Hermes Agent report semantic state and session identity. OMP and Qoder CLI report semantic state but do not provide native session restore. Custom socket integrations can report state when they define state that is not visible in the native terminal UI.
|
||||
|
||||
Some integrations also report native agent session references. If `[session] resume_agents_on_restore = true` is enabled, Herdr uses official session references to resume Claude Code, Codex, Pi, Hermes Agent, and OpenCode panes after a Herdr server restart.
|
||||
Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, GitHub Copilot CLI, Pi, Hermes Agent, and OpenCode panes after a Herdr server restart unless `[session] resume_agents_on_restore = false` disables it.
|
||||
|
||||
Native session restore requires current Herdr integrations: Pi integration version `2`, Claude Code version `4`, Codex version `4`, OpenCode version `2`, or Hermes Agent version `2`. OMP integration version `2` reports agent state only. Check installed versions with `herdr integration status`.
|
||||
Native session restore requires current Herdr integrations: Pi integration version `2`, Claude Code version `5`, Codex version `5`, GitHub Copilot CLI version `1`, OpenCode version `4`, or Hermes Agent version `2`. OMP integration version `2` and Qoder CLI integration version `1` report agent state only. Check installed versions with `herdr integration status`.
|
||||
|
||||
## Pi
|
||||
|
||||
|
|
@ -91,7 +93,7 @@ Install the Claude Code hook:
|
|||
herdr integration install claude
|
||||
```
|
||||
|
||||
The hook reports agent state to the local Herdr socket when Claude Code exposes hook events.
|
||||
The hook reports Claude Code session identity to the local Herdr socket on session start. Claude Code state comes from Herdr's screen detection.
|
||||
|
||||
Herdr uses `~/.claude` by default, or `CLAUDE_CONFIG_DIR` when set. The Claude config directory must already exist. Install writes `hooks/herdr-agent-state.sh` and updates `settings.json` with Herdr hook entries. Uninstall removes the matching hook entries and deletes the hook script.
|
||||
|
||||
|
|
@ -103,10 +105,24 @@ Install the Codex hook:
|
|||
herdr integration install codex
|
||||
```
|
||||
|
||||
Codex state is reported through the same local socket API used by other integrations.
|
||||
The Codex hook reports session identity through the same local socket API used by other integrations. Codex state comes from Herdr's screen detection.
|
||||
|
||||
Herdr uses `~/.codex` by default, or `CODEX_HOME` when set. The Codex config directory must already exist. Install writes `herdr-agent-state.sh`, updates `hooks.json`, and ensures `[features] hooks = true` in `config.toml`. It also removes the deprecated top-level `codex_hooks` flag when present. Uninstall removes Herdr entries from `hooks.json` and deletes the hook script, but leaves `config.toml` unchanged.
|
||||
|
||||
## GitHub Copilot CLI
|
||||
|
||||
Install the GitHub Copilot CLI hook:
|
||||
|
||||
```bash
|
||||
herdr integration install copilot
|
||||
```
|
||||
|
||||
Copilot state is reported through the same local socket API used by other integrations.
|
||||
|
||||
Herdr uses `~/.copilot` by default, or `COPILOT_HOME` when set. The Copilot config directory must already exist. Install writes `hooks/herdr-agent-state.sh` and updates `settings.json` with Herdr hook entries. The hook maps prompt submission, tool use, post-tool progress after approvals, `ask_user` prompts, `exit_plan_mode` plan review prompts, permission notifications, agent idle notifications, turn stops, and session exits into Herdr state. Uninstall removes Herdr entries from `settings.json` and deletes the hook script.
|
||||
|
||||
After Copilot emits a session-bearing event, Herdr can use the reported session id to resume the pane with `copilot --resume=<id>`.
|
||||
|
||||
## OpenCode
|
||||
|
||||
Install the OpenCode plugin:
|
||||
|
|
@ -117,7 +133,7 @@ herdr integration install opencode
|
|||
|
||||
Herdr writes the plugin to `~/.config/opencode/plugins/herdr-agent-state.js`. The OpenCode config directory must already exist. Uninstall removes only that plugin file.
|
||||
|
||||
The plugin reports semantic state while OpenCode runs inside a Herdr pane. After OpenCode emits a session-bearing event, Herdr can use the reported session id to resume the pane with `opencode --session <id>`.
|
||||
The plugin reports session identity while OpenCode runs inside a Herdr pane. After OpenCode emits a session-bearing event, Herdr can use the reported session id to resume the pane with `opencode --session <id>`. OpenCode state comes from Herdr's screen detection.
|
||||
|
||||
## Hermes Agent
|
||||
|
||||
|
|
@ -165,7 +181,6 @@ User hooks that run next to a Herdr-managed integration should use metadata inst
|
|||
herdr pane report-metadata "$HERDR_PANE_ID" \
|
||||
--source user:claude-title \
|
||||
--agent claude \
|
||||
--applies-to-source herdr:claude \
|
||||
--title "Refactor auth middleware" \
|
||||
--display-agent "Claude: auth" \
|
||||
--custom-status "refactor auth" \
|
||||
|
|
|
|||
|
|
@ -92,6 +92,8 @@ herdr --remote workbox
|
|||
|
||||
Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks `~/.local/bin/herdr`. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.
|
||||
|
||||
By default, `herdr --remote` runs the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings. Existing user keepalive settings win. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated bridge config.
|
||||
|
||||
By default, remote attach uses the normal restart/stop flow if it needs to replace or restart a running remote server. To opt into experimental live handoff for a supported running remote server, pass `--handoff`:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -51,6 +51,8 @@ After detaching, run `herdr` again to reattach to the same session.
|
|||
|
||||
Herdr is mouse-native. You can click panes, tabs, workspaces, and agents; drag borders; drag-select text to copy it to your clipboard; double-click a token to copy it directly; and use right-click menus. Copying does not require Ctrl+C.
|
||||
|
||||
If you configure `ui.right_click_passthrough_modifier`, that modifier plus right-click sends right-click, hold, and drag gestures to mouse-reporting pane apps.
|
||||
|
||||
Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and visible `http://` or `https://` URLs. The portable terminal-native fallback is Shift-Ctrl-click on Linux or Shift-Cmd-click on macOS.
|
||||
|
||||
## Copy from the keyboard
|
||||
|
|
|
|||
|
|
@ -40,26 +40,30 @@ When enabled, Herdr stores saved pane history in `session-history.json` next to
|
|||
|
||||
Some agents can resume their own conversation sessions. Herdr can use official integration-reported session references to restart supported agent panes after a Herdr server restart.
|
||||
|
||||
Enable it with:
|
||||
This is enabled by default. Disable it with:
|
||||
|
||||
```toml
|
||||
[session]
|
||||
resume_agents_on_restore = true
|
||||
resume_agents_on_restore = false
|
||||
```
|
||||
|
||||
When enabled, Herdr only resumes panes that reported a native session reference through a current official Herdr integration.
|
||||
Herdr only resumes panes that reported a native session reference through a current official Herdr integration.
|
||||
|
||||
After a client attaches and provides terminal size and theme context, Herdr resumes eligible restored agent panes across workspaces and tabs without waiting for each pane to be focused.
|
||||
|
||||
Native session restore requires these Herdr integration versions or newer:
|
||||
|
||||
| Agent | Minimum Herdr integration version | Resume command |
|
||||
| --- | --- | --- |
|
||||
| Pi | `2` | `pi --session <path-or-id>` |
|
||||
| Claude Code | `4` | `claude --resume <id>` |
|
||||
| Codex | `4` | `codex resume <id>` |
|
||||
| OpenCode | `2` | `opencode --session <id>` |
|
||||
| Claude Code | `5` | `claude --resume <id>` |
|
||||
| Codex | `5` | `codex resume <id>` |
|
||||
| GitHub Copilot CLI | `1` | `copilot --resume=<id>` |
|
||||
| OpenCode | `4` | `opencode --session <id>` |
|
||||
| Hermes Agent | `2` | `hermes --resume <id>` |
|
||||
|
||||
OMP integration version `2` reports agent state, but does not report native session references for restore.
|
||||
Qoder CLI integration version `1` reports agent state, but does not report native session references for restore.
|
||||
|
||||
Run `herdr integration status` to check installed integration versions. Reinstall outdated integrations with `herdr integration install <agent>`.
|
||||
|
||||
|
|
|
|||
|
|
@ -73,7 +73,7 @@ Raw socket method names use dot notation:
|
|||
| Workspace | `workspace.create`, `workspace.list`, `workspace.get`, `workspace.focus`, `workspace.rename`, `workspace.close` |
|
||||
| Worktree | `worktree.list`, `worktree.create`, `worktree.open`, `worktree.remove` |
|
||||
| Tab | `tab.create`, `tab.list`, `tab.get`, `tab.focus`, `tab.rename`, `tab.close` |
|
||||
| Pane | `pane.split`, `pane.list`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.report_agent`, `pane.report_metadata`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
|
||||
| Pane | `pane.split`, `pane.list`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.report_agent`, `pane.report_agent_session`, `pane.report_metadata`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
|
||||
| Agent | `agent.list`, `agent.get`, `agent.read`, `agent.send`, `agent.rename`, `agent.focus`, `agent.start` |
|
||||
| Events | `events.subscribe`, `events.wait` |
|
||||
| Integrations | `integration.install`, `integration.uninstall` |
|
||||
|
|
@ -163,7 +163,22 @@ Integrations report agent state with `pane.report_agent`.
|
|||
|
||||
`custom_status` is visual. It can show a short label like `indexing` without changing semantic behavior.
|
||||
|
||||
Official integrations can also report a native session reference. `pane.get`, `pane.list`, `agent.get`, and `agent.list` expose a read-only `agent_session` object when Herdr has a stored native session reference:
|
||||
Session-only official integrations report native session references with `pane.report_agent_session`. State-reporting integrations can still include native session references in `pane.report_agent`. State-independent session reports do not affect waits, notifications, or rollups.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "req_2",
|
||||
"method": "pane.report_agent_session",
|
||||
"params": {
|
||||
"pane_id": "1-1",
|
||||
"source": "herdr:codex",
|
||||
"agent": "codex",
|
||||
"agent_session_id": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`pane.get`, `pane.list`, `agent.get`, and `agent.list` expose a read-only `agent_session` object when Herdr has a stored native session reference:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -190,7 +205,6 @@ Use `pane.report_metadata` when a user hook wants to customize presentation with
|
|||
"pane_id": "1-1",
|
||||
"source": "user:claude-title",
|
||||
"agent": "claude",
|
||||
"applies_to_source": "herdr:claude",
|
||||
"title": "Refactor auth middleware",
|
||||
"display_agent": "Claude: auth",
|
||||
"custom_status": "refactor auth",
|
||||
|
|
@ -204,7 +218,7 @@ Use `pane.report_metadata` when a user hook wants to customize presentation with
|
|||
}
|
||||
```
|
||||
|
||||
Metadata reports are display-only. Valid metadata can override the pane title, displayed agent name, compact custom status, and visible state labels. `working`, `blocked`, `idle`, waits, notifications, session restore, and rollups still come from the active agent state report. `agent` is an optional guard for the authoritative agent label; `applies_to_source` is an optional guard for the active lifecycle authority source. Use `display_agent` to change the visible name. `state_labels` keys must be `idle`, `working`, `blocked`, `done`, or `unknown`. Use clear fields such as `clear_custom_status: true` with the same `source` to remove one presentation override.
|
||||
Metadata reports are display-only. Valid metadata can override the pane title, displayed agent name, compact custom status, and visible state labels. `working`, `blocked`, `idle`, waits, notifications, and rollups still come from semantic state. Native session restore comes from stored official session references. `agent` is an optional guard for the authoritative agent label; `applies_to_source` is an optional guard for the active lifecycle authority source. Use `display_agent` to change the visible name. `state_labels` keys must be `idle`, `working`, `blocked`, `done`, or `unknown`. Use clear fields such as `clear_custom_status: true` with the same `source` to remove one presentation override.
|
||||
|
||||
## Event subscriptions
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue