From 17208b0641a702af60d96e15004f72f226bac0de Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Wed, 15 Jul 2026 19:23:30 +0300 Subject: [PATCH 1/4] docs: finalize next release documentation --- CHANGELOG.md | 39 ++ docs/next/CHANGELOG.md | 31 +- docs/next/README.md | 279 ++---------- .../src/content/docs/ja/socket-api.mdx | 54 ++- .../src/content/docs/zh-cn/socket-api.mdx | 54 ++- .../website/src/data/config-reference.json | 2 +- website/src/content/docs/agents.mdx | 14 +- website/src/content/docs/cli-reference.mdx | 22 +- website/src/content/docs/configuration.mdx | 337 +++++--------- website/src/content/docs/install.mdx | 2 +- website/src/content/docs/integrations.mdx | 13 +- website/src/content/docs/ja/agents.mdx | 14 +- website/src/content/docs/ja/cli-reference.mdx | 17 +- website/src/content/docs/ja/configuration.mdx | 395 +++++++--------- website/src/content/docs/ja/install.mdx | 2 +- website/src/content/docs/ja/integrations.mdx | 13 +- website/src/content/docs/ja/keyboard.mdx | 2 +- website/src/content/docs/ja/plugins.mdx | 27 +- website/src/content/docs/ja/socket-api.mdx | 89 +++- .../src/content/docs/ja/troubleshooting.mdx | 20 + website/src/content/docs/ja/windows-beta.mdx | 6 +- website/src/content/docs/keyboard.mdx | 2 +- website/src/content/docs/plugins.mdx | 39 +- website/src/content/docs/socket-api.mdx | 87 +++- website/src/content/docs/troubleshooting.mdx | 20 + website/src/content/docs/windows-beta.mdx | 6 +- website/src/content/docs/zh-cn/agents.mdx | 14 +- .../src/content/docs/zh-cn/cli-reference.mdx | 17 +- .../src/content/docs/zh-cn/configuration.mdx | 431 +++++++----------- website/src/content/docs/zh-cn/install.mdx | 2 +- .../src/content/docs/zh-cn/integrations.mdx | 13 +- website/src/content/docs/zh-cn/keyboard.mdx | 2 +- website/src/content/docs/zh-cn/plugins.mdx | 25 +- website/src/content/docs/zh-cn/socket-api.mdx | 89 +++- .../content/docs/zh-cn/troubleshooting.mdx | 20 + .../src/content/docs/zh-cn/windows-beta.mdx | 6 +- website/src/data/config-reference.json | 49 +- 37 files changed, 1142 insertions(+), 1112 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96a9613b..2dc1f55f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,45 @@ ## Unreleased +### 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 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) +- Added a searchable, version-matched configuration reference and a troubleshooting guide covering duplicate terminal key events, modified-arrow shell bindings, updates, remote access, and logs. (#1116, #1370) + +### Changed +- Expanded Space and Agent sidebar entries now use a packed layout by default; set the corresponding `row_gap` to `1` to restore the previous spacing. +- Refreshed the bundled Herdr agent skill for current public workspace, tab, and pane ids and the current CLI/API workflow. (#1297) +- Expanded Japanese and Simplified Chinese CLI documentation with shell completion setup and API schema usage. (#1151) + +### Fixed +- Collapsed Agent sidebar rows now follow the same ordering and click targets as the expanded panel, and their shortcut numbers are assigned by visible list position instead of repeating across workspaces. (#1168, #1344) +- Shifted indexed bindings such as `prefix+shift+1..9` now match terminals that report the corresponding punctuation characters. (#1184) +- Plugin-driven tab renames now immediately refresh tab-bar geometry and labels. (#1111, #1179, thanks @kovalov) +- New tabs, splits, layouts, and workspaces configured to follow the foreground directory now start from the focused pane's current working directory. (#1245) +- Amp, Codex, and Claude Code detection now recognizes current active-turn UI variants, including reordered Codex title spinners and Claude `/btw` turns. (#1208, #1281, #1366) +- Pi lifecycle state now reanchors after native session replacement, avoiding working panes that remain idle or tied to an abandoned session. (#943, #1189, thanks @dmmulroy) +- OMP lifecycle reports are now retried when startup races drop the first report. (#1310) +- WSL now uses Herdr's drawn cursor by default, matching the native Windows workaround for host cursor flicker. (#930) +- Live handoff now preserves explicit named-session socket paths, waits for slower server shutdowns, and flushes API responses before the old server exits. (#1180, thanks @dvic) +- The Windows installer no longer rewrites an existing config file or creates a duplicate onboarding line during first-run setup. (#1162) +- Config diagnostics now reach CLI-only and attached-client startup paths reliably and clearly identify fallback configuration behavior. +- Detached custom command children are now reaped after exit instead of accumulating zombie processes. (#1360) +- Renamed single tabs now remain visible in the Agents sidebar instead of losing their tab label. (#1369) +- Documentation search results are now scoped to the active locale and stable or preview channel. +- Horizontal wheel and trackpad events now reach pane applications that enable mouse reporting. (#1349) +- Copy mode `$` and End now stop at the final visible character on the row instead of jumping to the pane edge. (#1405) +- Split SGR mouse reports are now reassembled across input reads, and a preceding standalone Escape is preserved instead of being swallowed or leaked as mouse bytes. (#1334, #1382) +- Linux foreground-process discovery now stays within Herdr pane process trees instead of scanning unrelated host processes, reducing CPU use on busy multi-user systems. (#1399) +- Single-codepoint emoji chosen from the Windows emoji picker now reach panes when WezTerm's kitty keyboard support sends them as CSI-u events with associated text. (#1404) +- Outer-terminal focus gained and lost reports now reach the focused pane when its application enables focus reporting, restoring Neovim file autoreload and other focus-aware terminal behavior. (#1337) +- Native Windows servers now detach from the terminal console that launched them, so closing WezTerm, Windows Terminal, or another host terminal no longer stops persistent pane processes. (#1329) +- Windows API clients now remain connected while waiting for initial named-pipe request bytes, so `status server`, `api snapshot`, and other socket commands no longer intermittently fail with BrokenPipe. (#1279) +- `herdr --remote` now installs remote helper binaries without routing the binary stream through a multiline `/bin/sh -c` command, fixing installs for non-POSIX login shells such as xonsh. (#1203, thanks @nhumrich) + ## [0.7.3] - 2026-07-08 ### Fixed diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md index a3894b34..2dc1f55f 100644 --- a/docs/next/CHANGELOG.md +++ b/docs/next/CHANGELOG.md @@ -3,14 +3,38 @@ ## Unreleased ### Added -- Added independent `row_gap` settings for expanded Space and Agent sidebar entries. (#873) +- 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 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 detection with idle, working, and blocked screen states. (#1301, thanks @tontinton) +- Added Maki agent support. (#1301, #1302, thanks @tontinton) +- Added a searchable, version-matched configuration reference and a troubleshooting guide covering duplicate terminal key events, modified-arrow shell bindings, updates, remote access, and logs. (#1116, #1370) ### Changed -- Expanded Space and Agent sidebar entries now use a packed layout by default; set the corresponding `row_gap` to `1` to restore the previous spacing. (#873) +- Expanded Space and Agent sidebar entries now use a packed layout by default; set the corresponding `row_gap` to `1` to restore the previous spacing. +- Refreshed the bundled Herdr agent skill for current public workspace, tab, and pane ids and the current CLI/API workflow. (#1297) +- Expanded Japanese and Simplified Chinese CLI documentation with shell completion setup and API schema usage. (#1151) ### Fixed +- Collapsed Agent sidebar rows now follow the same ordering and click targets as the expanded panel, and their shortcut numbers are assigned by visible list position instead of repeating across workspaces. (#1168, #1344) +- Shifted indexed bindings such as `prefix+shift+1..9` now match terminals that report the corresponding punctuation characters. (#1184) +- Plugin-driven tab renames now immediately refresh tab-bar geometry and labels. (#1111, #1179, thanks @kovalov) +- New tabs, splits, layouts, and workspaces configured to follow the foreground directory now start from the focused pane's current working directory. (#1245) +- Amp, Codex, and Claude Code detection now recognizes current active-turn UI variants, including reordered Codex title spinners and Claude `/btw` turns. (#1208, #1281, #1366) +- Pi lifecycle state now reanchors after native session replacement, avoiding working panes that remain idle or tied to an abandoned session. (#943, #1189, thanks @dmmulroy) +- OMP lifecycle reports are now retried when startup races drop the first report. (#1310) +- WSL now uses Herdr's drawn cursor by default, matching the native Windows workaround for host cursor flicker. (#930) +- Live handoff now preserves explicit named-session socket paths, waits for slower server shutdowns, and flushes API responses before the old server exits. (#1180, thanks @dvic) +- The Windows installer no longer rewrites an existing config file or creates a duplicate onboarding line during first-run setup. (#1162) +- Config diagnostics now reach CLI-only and attached-client startup paths reliably and clearly identify fallback configuration behavior. +- Detached custom command children are now reaped after exit instead of accumulating zombie processes. (#1360) +- Renamed single tabs now remain visible in the Agents sidebar instead of losing their tab label. (#1369) +- Documentation search results are now scoped to the active locale and stable or preview channel. +- Horizontal wheel and trackpad events now reach pane applications that enable mouse reporting. (#1349) +- Copy mode `$` and End now stop at the final visible character on the row instead of jumping to the pane edge. (#1405) +- Split SGR mouse reports are now reassembled across input reads, and a preceding standalone Escape is preserved instead of being swallowed or leaked as mouse bytes. (#1334, #1382) +- Linux foreground-process discovery now stays within Herdr pane process trees instead of scanning unrelated host processes, reducing CPU use on busy multi-user systems. (#1399) - Single-codepoint emoji chosen from the Windows emoji picker now reach panes when WezTerm's kitty keyboard support sends them as CSI-u events with associated text. (#1404) - Outer-terminal focus gained and lost reports now reach the focused pane when its application enables focus reporting, restoring Neovim file autoreload and other focus-aware terminal behavior. (#1337) - Native Windows servers now detach from the terminal console that launched them, so closing WezTerm, Windows Terminal, or another host terminal no longer stops persistent pane processes. (#1329) @@ -41,7 +65,6 @@ - Added `herdr terminal session control` for bridge processes that need live ANSI frames plus input, resize, scroll, release, and takeover authority. - Added `ui.hide_tab_bar_when_single_tab` to hide the tab row when a workspace has one tab. (#448) - Added Japanese and Simplified Chinese website docs. -- Added session-modal popup terminal panes for custom command keybindings and plugin panes, so tools such as `lazygit` or plugin pickers can open without changing the tab layout. (#1125) ### Changed - The mobile switcher now starts from an agents-first summary and renders worktrees as a tree, making narrow terminals easier to scan. diff --git a/docs/next/README.md b/docs/next/README.md index ff8739b6..530b266a 100644 --- a/docs/next/README.md +++ b/docs/next/README.md @@ -6,7 +6,16 @@

- herdr.dev · install · quick start · supported agents · integrations · configuration · socket api · sponsor + herdr.dev · install · quick start · docs · sponsors +

+ +

+ AGPL 3.0 license + total GitHub release downloads + GitHub stars + latest stable release + Homebrew version + follow @herdrdev on X

--- @@ -15,7 +24,12 @@ https://github.com/user-attachments/assets/043ec09f-4bdd-41d5-aee0-8fda6b83e267 **agent multiplexer that lives in your terminal.** -workspaces, tabs, panes. mouse-native: click, drag, split. every agent at a glance: blocked, working, done. detach and reattach, agents keep running. no gui app, no electron, no mac-only native wrapper. you see the agent's own terminal, not someone's interpretation of it. +- **every agent at a glance** — blocked, working, done. real terminal views, not a wrapped interpretation. +- **detach, agents keep running** — reattach from any terminal, or over ssh. sessions survive restarts. +- **agents can use herdr too** — a pure socket api: agents spawn panes, read output, wait on each other. [agent skill →](https://herdr.dev/docs/agent-skill/) +- **keyboard and mouse, both first-class** — tmux-style prefix keys *and* click, drag, split. pick per moment, not per tool. +- **plugins** — extend panes and workflows. [browse the marketplace →](https://herdr.dev/plugins/) +- **one rust binary, no electron** — runs in whatever terminal you already use. --- @@ -25,255 +39,29 @@ workspaces, tabs, panes. mouse-native: click, drag, split. every agent at a glan curl -fsSL https://herdr.dev/install.sh | sh ``` -on windows preview beta: +or `brew install herdr` · `mise use -g herdr` · windows beta: `powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"` · [binaries](https://github.com/ogulcancelik/herdr/releases) -```powershell -powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex" -``` - -or install with homebrew: - -```bash -brew install herdr -``` - -or install with mise: - -```bash -mise use -g herdr -``` - -if mise reports `herdr not found in mise tool registry`, update mise and retry. older mise versions predate the herdr registry entry; `mise use -g github:ogulcancelik/herdr` works as a temporary fallback. - -or download the stable Linux/macOS binary from [releases](https://github.com/ogulcancelik/herdr/releases). Native Windows binaries are preview-only beta builds. - -## quick start - -Start Herdr in the directory where the work lives: +then start it where the work lives: ```bash herdr ``` -Herdr starts or attaches to one background session server. When a session has no workspaces, Herdr opens one automatically. Run an agent in the root pane. Press `ctrl+b`, then `shift+n` to create another workspace, `ctrl+b`, then `v` or `minus` to split panes, `ctrl+b`, then `c` to create a tab, and `ctrl+b`, then `w` to switch workspaces. - -Press `ctrl+b q` to detach the client. The server and pane processes keep running. Open another terminal and run `herdr` again to reattach. - -## core concepts - -**Server and client.** By default, `herdr` attaches to a background server. Detaching closes only the client. `herdr server stop` stops the default server and kills its panes. Named sessions are separate server namespaces: use `herdr session attach work`, `herdr session stop work`, and `herdr session list` when you want fully separate runtime state. - -**Workspaces, tabs, panes.** A workspace is the project-level container. Tabs group panes inside a workspace. Panes are real terminal processes, not rewritten agent views. - -**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 `{`/`}`, search forward or backward with `/` or `?`, repeat with `n` or `N`, start selection with `v` or Space, copy with `y` or Enter, and leave with `q` or Esc. Esc clears an active selection or search before exiting. 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 `, then run `herdr session attach ` 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 can add native session identity for restore, semantic state reports, or both. - -## update - -Herdr notifies you when a new version is available. Run manually: - -```bash -herdr update -``` - -`herdr update` is for installs managed by Herdr's own installer. Homebrew, mise, and Nix installs update through `brew upgrade herdr`, `mise upgrade herdr`, or your Nix workflow, then use the same stop-and-run-again flow if a session is still running the old server. Linux and macOS direct installs can opt into development preview builds with `herdr channel set preview` and return to stable with `herdr channel set stable`. Windows beta installs are preview-only for now. 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. - -Linux and macOS direct installs use the stable update channel by default. Windows beta installs default to preview. To test preview builds from `master` before the next stable release: - -```bash -herdr channel set preview -``` - -To return Linux and macOS direct installs 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, mise, and Nix stay on stable and update through their package managers. - -## how it compares - -| | tmux | gui managers | herdr | -|--------------------------|------|--------------|-------| -| persistent sessions | ✓ | — | ✓ | -| detach / reattach | ✓ | — | ✓ | -| panes, tabs, workspaces | ✓ | ✓ | ✓ | -| agent awareness | — | ✓ | ✓ | -| lives in your terminal | ✓ | — | ✓ | -| real terminal views | ✓ | — | ✓ | -| mouse-native | — | ✓ | ✓ | -| lightweight binary | ✓ | — | ✓ | -| agents can orchestrate | ? | ? | ✓ | - -tmux gives you persistence and panes, but it was built before agents existed. gui managers show agent state, but they make you leave your terminal and use their wrapped view. herdr is persistence and awareness in one tool that stays out of your way. - -## remote and attach - -Herdr works over normal SSH. Run it on the remote host, detach, and reattach later: - -``` -ssh you@yourserver -herdr -``` - -You can also attach from your local terminal without opening a shell first: - -```bash -herdr --remote workbox -herdr --remote ssh://you@yourserver:2222 -``` - -Remote attach adds fallback SSH keepalives and connection reuse 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 -herdr agent attach -herdr terminal attach -``` - -See [persistence and remote docs](https://herdr.dev/docs/persistence-remote/) for remote keybinding, named-session, and handoff details. - -## agent awareness - -the sidebar shows which agents are blocked, working, or done. workspaces roll up to their most urgent state so you can scan the full list at a glance. - -states: - -- 🔴 **blocked** — agent needs input or approval -- 🟡 **working** — agent is actively running -- 🔵 **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. official claude code, codex, github copilot cli, devin, droid, kimi code cli, qodercli, and cursor agent cli integrations provide session restore identity; pi, omp, kimi code cli, opencode, kilo code cli, hermes, mastracode, and custom socket integrations can report their own state. - -## lives in your terminal - -not a gui window, not a web dashboard, not electron. herdr runs inside whatever terminal you already use. single rust binary, no dependencies. works inside tmux as the outer terminal environment. - -## what you get - -- **workspaces** — organized around git repos or folder names, each with its own tabs and panes -- **tabs** — first-class in the socket api and cli -- **copy-friendly** — drag-select pane text, double-click tokens, or use keyboard copy mode with `prefix+[`, `h/j/k/l`, `{`/`}`, `v`, and `y` -- **notifications** — sounds and toasts for background events; tab-aware suppression -- **18 built-in themes** — catppuccin, terminal, tokyo night, gruvbox, one, solarized, kanagawa, rosé pine, vesper, and light variants for the main palettes -- **session persistence** — pane processes survive client detach; sessions restore panes after full restart, with opt-in recent screen history - -## agents can use herdr too - -The local Unix socket lets agents create workspaces, split or zoom panes, spawn helpers, read output, and wait for state changes. Install the reusable skill with: - -```bash -npx skills add ogulcancelik/herdr --skill herdr -g -``` - -Start with the [agent skill docs](https://herdr.dev/docs/agent-skill/), [socket API docs](https://herdr.dev/docs/socket-api/), and [`SKILL.md`](./SKILL.md). - -## supported agents - -automatic detection works out of the box. process name matching plus terminal output heuristics. - -| agent | idle / done | working | blocked | -|-------|-------------|---------|---------| -| [pi](https://pi.dev) | ✓ | ✓ | partial | -| [claude code](https://docs.anthropic.com/en/docs/claude-code) | ✓ | ✓ | ✓ | -| [codex](https://github.com/openai/codex) | ✓ | ✓ | ✓ | -| [droid](https://factory.ai) | ✓ | ✓ | ✓ | -| [amp](https://ampcode.com) | ✓ | ✓ | ✓ | -| [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/) | ✓ | ✓ | ✓ | -| [devin cli](https://docs.devin.ai/cli) | ✓ | ✓ | ✓ | -| cursor agent | ✓ | ✓ | ✓ | -| antigravity cli | ✓ | ✓ | ✓ | -| kimi code cli | ✓ | ✓ | ✓ | -| [github copilot cli](https://github.com/features/copilot) | ✓ | ✓ | ✓ | -| [qodercli](https://qoder.com/cli) | ✓ | ✓ | ✓ | -| [maki](https://github.com/tontinton/maki) | ✓ | ✓ | ✓ | -| [kiro cli](https://kiro.dev/docs/cli/) | ✓ | ✓ | — | - -detected but not fully tested: gemini cli, cline. - -for agents outside the built-in list, herdr still works as a terminal multiplexer with workspaces, panes, and tiling. custom integrations can report agent labels over the socket api. see the [socket api docs](https://herdr.dev/docs/socket-api/). - -### direct integrations - -official integrations have two roles. claude code, codex, github copilot cli, devin, droid, qodercli, and cursor agent cli report session identity for native restore, while their state still comes from screen detection. pi, omp, kimi code cli, opencode, kilo code cli, hermes, and mastracode report both semantic state and session identity. 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 devin -herdr integration install droid -herdr integration install kimi -herdr integration install opencode -herdr integration install kilo -herdr integration install hermes -herdr integration install mastracode -herdr integration install qodercli -herdr integration install cursor -``` - -see the [integrations docs](https://herdr.dev/docs/integrations/) for setup details. - -## keybindings - -Press `ctrl+b` to enter prefix mode. Default actions are prefix-first and tmux-like: - -| key | action | -|-----|--------| -| `prefix+c` | new tab | -| `prefix+n` / `prefix+p` | next / previous tab | -| `prefix+1..9` | switch tab | -| `prefix+w` | workspace navigation | -| `prefix+g` | session navigator | -| `prefix+shift+n` | new workspace | -| `prefix+shift+g` | new worktree | -| `prefix+shift+w` | rename workspace | -| `prefix+shift+d` | close workspace | -| `prefix+h/j/k/l` | focus pane | -| `prefix+shift+h/j/k/l` | swap pane | -| `prefix+v` / `prefix+minus` | split pane | -| `prefix+x` | close pane | -| `prefix+b` | toggle sidebar | -| `prefix+z` | zoom pane | -| `prefix+r` | resize mode | -| `prefix+q` | detach | - -Mouse is supported throughout. Resize mode uses `h`/`l` for width, `j`/`k` for height, and `esc` to exit. Full syntax, optional actions, indexed bindings, and custom command bindings live in the [configuration docs](https://herdr.dev/docs/configuration/). - -## configuration - -config file: `~/.config/herdr/config.toml` - -```bash -herdr --default-config # print full default config -``` - -In-app settings cover theme, sound, and toast preferences. Herdr writes logs under `~/.config/herdr/`; in persistent session mode, `herdr-client.log` and `herdr-server.log` are usually the useful files. Full configuration and logging details live in the [configuration docs](https://herdr.dev/docs/configuration/). +run your agents, split panes, walk away. `ctrl+b q` detaches, `herdr` reattaches. [quick start →](https://herdr.dev/docs/quick-start/) ## docs -- [quick start](https://herdr.dev/docs/quick-start/) — first session, panes, copy, and named sessions -- [install](https://herdr.dev/docs/install/) — install, update, Homebrew, mise, 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, cursor agent cli, github copilot cli, droid, kimi code cli, opencode, kilo code cli, hermes, mastracode, qodercli integrations -- [`SKILL.md`](./SKILL.md) — reusable agent skill -- [socket api](https://herdr.dev/docs/socket-api/) — socket protocol and cli reference +everything lives at [herdr.dev/docs](https://herdr.dev/docs/): [quick start](https://herdr.dev/docs/quick-start/) · [concepts](https://herdr.dev/docs/concepts/) · [supported agents](https://herdr.dev/docs/agents/) · [keyboard](https://herdr.dev/docs/keyboard/) · [configuration](https://herdr.dev/docs/configuration/) · [session state](https://herdr.dev/docs/session-state/) · [remote](https://herdr.dev/docs/persistence-remote/) · [integrations](https://herdr.dev/docs/integrations/) · [plugins](https://herdr.dev/docs/plugins/) · [socket api](https://herdr.dev/docs/socket-api/) + +## sponsors + +herdr is built full-time, in the open. sponsoring directly funds development, stability, and the path to a real agent runtime. + +### gold + +Terminal Trove + +[**→ become a sponsor**](https://github.com/sponsors/ogulcancelik) · enterprise / partnership: hey@herdr.dev · see [SPONSORS.md](./SPONSORS.md) for tiers. thank you 🐑 ## agent instructions @@ -285,18 +73,11 @@ if you are an ai agent helping with this repository, read [`AGENTS.md`](./AGENTS git clone https://github.com/ogulcancelik/herdr cd herdr cargo build --release -./target/release/herdr just test # unit tests just check # formatting, tests, and maintenance checks ``` -## sponsors - -herdr is built full-time, in the open, with no revenue behind it. sponsoring directly funds development, stability, and the path to a real agent runtime. - -[**→ become a sponsor**](https://github.com/sponsors/ogulcancelik) · enterprise / partnership: hey@herdr.dev · see [SPONSORS.md](./SPONSORS.md) for tiers. thank you 🐑 - ## license Herdr is dual-licensed: diff --git a/docs/next/website/src/content/docs/ja/socket-api.mdx b/docs/next/website/src/content/docs/ja/socket-api.mdx index 03b98958..975336ca 100644 --- a/docs/next/website/src/content/docs/ja/socket-api.mdx +++ b/docs/next/website/src/content/docs/ja/socket-api.mdx @@ -95,12 +95,13 @@ herdr pane read w1:p2 --source recent --lines 50 | サーバー | `ping`、`server.stop`、`server.reload_config`、`server.agent_manifests`、`server.reload_agent_manifests` | | 通知 | `notification.show` | | クライアント | `client.window_title.set`、`client.window_title.clear` | -| ワークスペース | `workspace.create`、`workspace.list`、`workspace.get`、`workspace.focus`、`workspace.rename`、`workspace.report_metadata`、`workspace.close` | +| セッション | `session.snapshot` | +| ワークスペース | `workspace.create`、`workspace.list`、`workspace.get`、`workspace.focus`、`workspace.rename`、`workspace.move`、`workspace.report_metadata`、`workspace.close` | | Worktree | `worktree.list`、`worktree.create`、`worktree.open`、`worktree.remove` | -| タブ | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.close` | -| ペイン | `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.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` | +| タブ | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.move`、`tab.close` | +| ペイン | `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.export`、`layout.apply`、`layout.set_split_ratio` | | エージェント | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send`、`agent.rename`、`agent.focus`、`agent.start` | | イベント | `events.subscribe`、`events.wait` | | インテグレーション | `integration.install`、`integration.uninstall` | @@ -108,6 +109,10 @@ herdr pane read w1:p2 --source recent --lines 50 一部の CLI コマンドは、これらのメソッドの便利ラッパーです。たとえば `herdr agent wait` は、エージェントターゲットを解決してからペインのエージェント状態イベントを購読します。 +`session.snapshot` は、独自のローカルランタイムキャッシュを持つクライアント向けに、一度限りのブートストラップスナップショットを返します。レスポンスには、バージョン/プロトコルメタデータ、フォーカス中のワークスペース/タブ/ペイン id、ワークスペース、タブ、ペイン、タブレイアウト、エージェントの各レコードが含まれます。これは購読ではありません。取得後はリソースイベントを購読し、そのイベントでローカルキャッシュを更新してください。再接続後やキャッシュが古い可能性がある場合は、`session.snapshot` を再度呼び出します。ワークスペースレコードには、関連付けられた worktree の出自情報も含まれます。リポジトリ全体の worktree 検出には引き続き `worktree.list` を使います。 + +CLI の `herdr api snapshot` は、クライアントやエージェントが簡単にブートストラップできるよう、現在の `session.snapshot` レスポンスを JSON で出力します。 + ペイン制御メソッドは `w1:p1` のような公開ペイン id を使います。スキーマ上 `pane_id` が省略可能なメソッドは、省略時にサーバーのアクティブなフォーカス中ペインを使います。`pane.move` は常に送信元の `pane_id` を要求します。 `pane.send_keys` と `pane.send_input.keys` は Herdr のキーコンボ文字列を受け付けます: 通常の印字可能キー、`enter` や `esc` のような特殊キー、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` のような修飾キーコード、`f1` のようなファンクションキー、`minus` や `plus` のような名前付き記号です。`prefix+` のバインド文字列は受け付けません。 @@ -126,6 +131,35 @@ herdr pane read w1:p2 --source recent --lines 50 `pane.current` は単一の `PaneInfo` を返します。`caller_pane_id` があるときはそのペインを返します。省略時はアクティブなフォーカス中ペインを返します。 +ターミナルのスクロール情報を取得できる場合、`PaneInfo` には `scroll` が含まれます: + +```json +{ + "offset_from_bottom": 12, + "max_offset_from_bottom": 240, + "viewport_rows": 30 +} +``` + +クライアントは `offset_from_bottom == 0` を最下部にいる状態として扱えます。 + +### 実験的なペイングラフィックス + +ペイングラフィックスを使うと、プラグインがペイン上に画像データを配置できます。`[experimental].kitty_graphics = true` の場合にのみ利用でき、それ以外ではすべてのペイングラフィックスメソッドが `feature_disabled` を返します。`pane.graphics.info` はグラフィックスレイヤーを作成せず、接続中クライアントのセルの幅と高さをピクセル単位で返します。`pane.graphics.set` は `data_base64` の `png`、`rgb`、`rgba` データを受け取り、`pane.graphics.clear` はレイヤーを削除します。 + +```json +{"id":"graphics_info","method":"pane.graphics.info","params":{"pane_id":"w1:p1"}} +{"id":"graphics_set","method":"pane.graphics.set","params":{"pane_id":"w1:p1","format":"png","image_width":800,"image_height":600,"data_base64":"...","placement":{"viewport_col":0,"viewport_row":0,"grid_cols":80,"grid_rows":30}}} +{"id":"graphics_clear","method":"pane.graphics.clear","params":{"pane_id":"w1:p1"}} +``` + +フレームを繰り返し送る場合は、`pane.graphics.stream` で専用ソケットを開きます。Herdr が `ok` を返した後、フレームごとに 1 つの JSON ヘッダーと正確に `data_length` バイトの生データを送ります。ソケットが閉じるまでストリームがそのペインのグラフィックスレイヤーを所有し、同時に set、clear、stream を要求すると `stream_conflict` を返します。 + +```json +{"id":"graphics_stream","method":"pane.graphics.stream","params":{"pane_id":"w1:p1"}} +{"format":"png","image_width":800,"image_height":600,"data_length":12345,"placement":{"viewport_col":0,"viewport_row":0,"grid_cols":80,"grid_rows":30}} +``` + `pane.layout` は、`workspace_id`、`tab_id`、`zoomed`、外側の `area`、`focused_pane_id`、ペインの矩形、分割の矩形/比率を含むタブレイアウトのスナップショットを返します。`pane.neighbor` と `pane.edges` は同じレイアウトスナップショットを含むので、クライアントは非公開のレイアウト状態なしに次の判断を下せます。 `pane.process_info` は、ペインのシェル pid、利用可能な場合はフォアグラウンドプロセスグループ id、そしてプラットフォームが公開している場合は pid、名前、argv/cmdline、cwd を含むフォアグラウンドプロセスを返します。 @@ -169,6 +203,12 @@ herdr pane read w1:p2 --source recent --lines 50 } ``` +`layout.set_split_ratio` は、タブレイアウト内の既存の分割比率を更新します。レスポンスは、更新済みの移植可能な `layout` を含む `type: "layout_split_ratio_set"` です。 + +```json +{"id":"req_ratio","method":"layout.set_split_ratio","params":{"tab_id":"w1:t1","path":[],"ratio":0.6}} +``` + プロセスを起動するメソッドは `env` オブジェクトを受け付けます。Herdr はそのキー/値ペアを新しく起動されるプロセスにのみ適用します。Herdr は管理下のペインプロセスに `HERDR_SOCKET_PATH`、`HERDR_ENV=1`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID` も注入します。呼び出し側が与えた環境変数と衝突した場合、Herdr 管理の変数が権威を持ちます。 `pane.swap` は方向指定と明示指定の両方の形式をサポートします: @@ -521,8 +561,10 @@ workspace の get/list 応答は結果の `tokens` マップを公開し、ス 最初のレスポンスは購読の確認応答です。以降の行はプッシュされるイベントです。 -ワークスペースのイベント購読には `workspace.created`、`workspace.updated`、`workspace.metadata_updated`、`workspace.renamed`、`workspace.closed`、`workspace.focused` があります。`workspace.metadata_updated` はプラグインイベントフックを実行せずにトークン変更と TTL 失効を報告します。その他のワークスペースイベントは Herdr の UI/ランタイムのライフサイクルを記述します。ワークスペースが worktree グループに属している場合、`workspace.created` は任意の `workspace.worktree` 出自情報を含みます。削除前に Herdr がまだ識別できる場合、`workspace.closed` は最終的な `workspace` スナップショットを含みます。 -ペインのイベント購読には `pane.created`、`pane.updated`、`pane.closed`、`pane.focused`、`pane.moved`、`pane.exited`、`pane.agent_detected`、`pane.output_matched`、`pane.agent_status_changed` があります。ターミナルタイトルの変更は `pane.updated` を発行することがありますが、生のタイトルでスピナーだけが変化し、`terminal_title_stripped` が変わらない場合は発行しません。 +ワークスペースのイベント購読には `workspace.created`、`workspace.updated`、`workspace.metadata_updated`、`workspace.renamed`、`workspace.moved`、`workspace.closed`、`workspace.focused` があります。`workspace.metadata_updated` はプラグインイベントフックを実行せずにトークン変更と TTL 失効を報告します。その他のワークスペースイベントは Herdr の UI/ランタイムのライフサイクルを記述します。ワークスペースが worktree グループに属している場合、`workspace.created` は任意の `workspace.worktree` 出自情報を含みます。`workspace.moved` は、移動した `workspace_id`、要求された `insert_index`、更新済みの順序付き `workspaces` リストを含みます。削除前に Herdr がまだ識別できる場合、`workspace.closed` は最終的な `workspace` スナップショットを含みます。 +タブのイベント購読には `tab.created`、`tab.closed`、`tab.focused`、`tab.renamed`、`tab.moved` があります。`tab.moved` は、移動した `tab_id`、`workspace_id`、要求された `insert_index`、そのワークスペースの更新済みの順序付き `tabs` リストを含みます。 +ペインのイベント購読には `pane.created`、`pane.updated`、`pane.closed`、`pane.focused`、`pane.moved`、`pane.exited`、`pane.agent_detected`、`pane.output_matched`、`pane.agent_status_changed`、`pane.scroll_changed` があります。ターミナルタイトルの変更は `pane.updated` を発行することがありますが、生のタイトルでスピナーだけが変化し、`terminal_title_stripped` が変わらない場合は発行しません。`pane.scroll_changed` は 1 つの `pane_id` を対象とし、Herdr がスクロールスナップショットの変化を検出するたびに `pane_id`、`workspace_id`、現在の `scroll` 情報を発行します。 +レイアウトのイベント購読には `layout.updated` があります。このイベントは 1 つのタブについて更新済みの `PaneLayoutSnapshot` を運びます。`session.snapshot` でブートストラップするクライアントは、同じ `workspace_id` と `tab_id` のキャッシュ済みレイアウトを置き換えてください。 worktree のイベント購読には `worktree.created`、`worktree.opened`、`worktree.removed` があります。worktree イベントは Git チェックアウトのライフサイクルを記述します。`worktree.created` は開かれた `workspace` と作成された `worktree` を含みます。`worktree.opened` は対象の `workspace`、開かれた `worktree`、`already_open` を含みます。`worktree.removed` は `workspace_id`、削除された `worktree`、`forced` を含みます。 diff --git a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx index 33190f1f..95f89be6 100644 --- a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx +++ b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx @@ -95,12 +95,13 @@ herdr pane read w1:p2 --source recent --lines 50 | 服务器 | `ping`、`server.stop`、`server.reload_config`、`server.agent_manifests`、`server.reload_agent_manifests` | | 通知 | `notification.show` | | 客户端 | `client.window_title.set`、`client.window_title.clear` | -| 工作区 | `workspace.create`、`workspace.list`、`workspace.get`、`workspace.focus`、`workspace.rename`、`workspace.report_metadata`、`workspace.close` | +| 会话 | `session.snapshot` | +| 工作区 | `workspace.create`、`workspace.list`、`workspace.get`、`workspace.focus`、`workspace.rename`、`workspace.move`、`workspace.report_metadata`、`workspace.close` | | Worktree | `worktree.list`、`worktree.create`、`worktree.open`、`worktree.remove` | -| 标签页 | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.close` | -| 窗格 | `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.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` | +| 标签页 | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.move`、`tab.close` | +| 窗格 | `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.export`、`layout.apply`、`layout.set_split_ratio` | | 智能体 | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send`、`agent.rename`、`agent.focus`、`agent.start` | | 事件 | `events.subscribe`、`events.wait` | | 集成 | `integration.install`、`integration.uninstall` | @@ -108,6 +109,10 @@ herdr pane read w1:p2 --source recent --lines 50 一些 CLI 命令是这些方法的便捷包装。比如 `herdr agent wait` 先解析智能体目标,然后订阅窗格智能体状态事件。 +`session.snapshot` 为维护本地运行时缓存的客户端返回一次性引导快照。响应包含版本/协议元数据、当前聚焦的工作区/标签页/窗格 id、工作区记录、标签页记录、窗格记录、标签页布局快照和智能体记录。它不是订阅;读取后应订阅资源事件,并根据事件更新本地缓存。重新连接后或本地缓存可能已过期时,再次调用 `session.snapshot`。工作区记录也包含关联 worktree 的来源信息。完整的仓库 worktree 发现仍使用 `worktree.list`。 + +CLI 的 `herdr api snapshot` 会把当前 `session.snapshot` 响应输出为 JSON,让客户端和智能体可以简单地完成引导。 + 窗格控制方法使用 `w1:p1` 这类公开窗格 id。schema 中 `pane_id` 可选的方法,在省略它时使用服务器当前聚焦的活动窗格。`pane.move` 总是要求来源 `pane_id`。 `pane.send_keys` 和 `pane.send_input.keys` 接受 Herdr 组合键字符串: 普通可打印键、`enter` 和 `esc` 这类特殊键、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` 这类修饰组合键、`f1` 这类功能键,以及 `minus` 和 `plus` 这类命名标点。它们不接受 `prefix+` 绑定字符串。 @@ -126,6 +131,35 @@ herdr pane read w1:p2 --source recent --lines 50 `pane.current` 返回单个 `PaneInfo`。带有 `caller_pane_id` 时,Herdr 返回那个窗格。省略时,Herdr 返回当前聚焦的活动窗格。 +终端滚动指标可用时,`PaneInfo` 包含 `scroll`: + +```json +{ + "offset_from_bottom": 12, + "max_offset_from_bottom": 240, + "viewport_rows": 30 +} +``` + +客户端可以把 `offset_from_bottom == 0` 视为位于底部。 + +### 实验性窗格图形 + +窗格图形允许插件在窗格上放置图像数据。它们只在 `[experimental].kitty_graphics = true` 时可用;否则所有窗格图形方法都返回 `feature_disabled`。调用 `pane.graphics.info` 会返回所连接客户端的单元格像素宽度和高度,但不会创建图形层。`pane.graphics.set` 接受 `data_base64` 中的 `png`、`rgb` 或 `rgba` 数据,`pane.graphics.clear` 删除该图层。 + +```json +{"id":"graphics_info","method":"pane.graphics.info","params":{"pane_id":"w1:p1"}} +{"id":"graphics_set","method":"pane.graphics.set","params":{"pane_id":"w1:p1","format":"png","image_width":800,"image_height":600,"data_base64":"...","placement":{"viewport_col":0,"viewport_row":0,"grid_cols":80,"grid_rows":30}}} +{"id":"graphics_clear","method":"pane.graphics.clear","params":{"pane_id":"w1:p1"}} +``` + +要重复发送帧,用 `pane.graphics.stream` 打开专用 socket。Herdr 回复 `ok` 后,每一帧发送一个 JSON 头,再发送恰好 `data_length` 字节的原始数据。socket 关闭前,该流拥有对应窗格的图形层;并发 set、clear 或 stream 请求返回 `stream_conflict`。 + +```json +{"id":"graphics_stream","method":"pane.graphics.stream","params":{"pane_id":"w1:p1"}} +{"format":"png","image_width":800,"image_height":600,"data_length":12345,"placement":{"viewport_col":0,"viewport_row":0,"grid_cols":80,"grid_rows":30}} +``` + `pane.layout` 返回标签页布局快照,包含 `workspace_id`、`tab_id`、`zoomed`、外层 `area`、`focused_pane_id`、窗格矩形和分割矩形/比例。`pane.neighbor` 和 `pane.edges` 也包含同一份布局快照,让客户端不需要私有布局状态就能做出下一步决策。 `pane.process_info` 返回窗格的 shell pid、可用时的前台进程组 id,以及平台暴露时带有 pid、名称、argv/cmdline 和 cwd 的前台进程。 @@ -169,6 +203,12 @@ herdr pane read w1:p2 --source recent --lines 50 } ``` +`layout.set_split_ratio` 更新标签页布局中已有分割的比例。响应是 `type: "layout_split_ratio_set"`,并包含更新后的可移植 `layout`。 + +```json +{"id":"req_ratio","method":"layout.set_split_ratio","params":{"tab_id":"w1:t1","path":[],"ratio":0.6}} +``` + 启动进程的方法接受一个 `env` 对象。Herdr 只把这些键值对应用到新启动的进程。Herdr 还向受管窗格进程注入 `HERDR_SOCKET_PATH`、`HERDR_ENV=1`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID` 和 `HERDR_PANE_ID`。与调用方提供的环境变量冲突时,Herdr 管理的变量保持权威。 `pane.swap` 支持按方向和显式两种形式: @@ -521,8 +561,10 @@ workspace 的 get/list 响应会公开生成的 `tokens` 映射,空间侧边栏 第一个响应确认订阅。之后的行是推送的事件。 -工作区事件订阅包括 `workspace.created`、`workspace.updated`、`workspace.metadata_updated`、`workspace.renamed`、`workspace.closed` 和 `workspace.focused`。`workspace.metadata_updated` 报告令牌变更和 TTL 到期,但不会调用插件事件钩子。其他工作区事件描述 Herdr UI/运行时的生命周期。当工作区属于 worktree 组时,`workspace.created` 包含可选的 `workspace.worktree` 来源信息。在移除前 Herdr 仍能识别时,`workspace.closed` 包含最终的 `workspace` 快照。 -窗格事件订阅包括 `pane.created`、`pane.updated`、`pane.closed`、`pane.focused`、`pane.moved`、`pane.exited`、`pane.agent_detected`、`pane.output_matched` 和 `pane.agent_status_changed`。终端标题变化可能发出 `pane.updated`,但如果原始标题只有旋转指示符发生变化且 `terminal_title_stripped` 不变,则不会发出。 +工作区事件订阅包括 `workspace.created`、`workspace.updated`、`workspace.metadata_updated`、`workspace.renamed`、`workspace.moved`、`workspace.closed` 和 `workspace.focused`。`workspace.metadata_updated` 报告令牌变更和 TTL 到期,但不会调用插件事件钩子。其他工作区事件描述 Herdr UI/运行时的生命周期。当工作区属于 worktree 组时,`workspace.created` 包含可选的 `workspace.worktree` 来源信息。`workspace.moved` 包含被移动的 `workspace_id`、请求的 `insert_index` 和更新后的有序 `workspaces` 列表。在移除前 Herdr 仍能识别时,`workspace.closed` 包含最终的 `workspace` 快照。 +标签页事件订阅包括 `tab.created`、`tab.closed`、`tab.focused`、`tab.renamed` 和 `tab.moved`。`tab.moved` 包含被移动的 `tab_id`、`workspace_id`、请求的 `insert_index` 和该工作区更新后的有序 `tabs` 列表。 +窗格事件订阅包括 `pane.created`、`pane.updated`、`pane.closed`、`pane.focused`、`pane.moved`、`pane.exited`、`pane.agent_detected`、`pane.output_matched`、`pane.agent_status_changed` 和 `pane.scroll_changed`。终端标题变化可能发出 `pane.updated`,但如果原始标题只有旋转指示符发生变化且 `terminal_title_stripped` 不变,则不会发出。`pane.scroll_changed` 只针对一个 `pane_id`,每当 Herdr 观察到滚动快照变化时,都会发出 `pane_id`、`workspace_id` 和当前 `scroll` 指标。 +布局事件订阅包括 `layout.updated`。该事件携带一个标签页更新后的 `PaneLayoutSnapshot`。使用 `session.snapshot` 引导的客户端应替换具有相同 `workspace_id` 和 `tab_id` 的缓存布局。 Worktree 事件订阅包括 `worktree.created`、`worktree.opened` 和 `worktree.removed`。Worktree 事件描述 Git 检出的生命周期。`worktree.created` 包含打开的 `workspace` 和创建的 `worktree`。`worktree.opened` 包含目标 `workspace`、打开的 `worktree` 和 `already_open`。`worktree.removed` 包含 `workspace_id`、被移除的 `worktree` 和 `forced`。 diff --git a/docs/next/website/src/data/config-reference.json b/docs/next/website/src/data/config-reference.json index 65a6f29e..c54e6dfb 100644 --- a/docs/next/website/src/data/config-reference.json +++ b/docs/next/website/src/data/config-reference.json @@ -992,7 +992,7 @@ "key": "ui.sound.agents.maki", "type": "enum", "default": "\"default\"", - "description": "Sound override for detected MastraCode agents.", + "description": "Sound override for detected Maki agents.", "values": [ "default", "on", diff --git a/website/src/content/docs/agents.mdx b/website/src/content/docs/agents.mdx index f752a297..b4c3146d 100644 --- a/website/src/content/docs/agents.mdx +++ b/website/src/content/docs/agents.mdx @@ -29,6 +29,7 @@ Automatic detection works out of the box for common coding agents. The important | Grok CLI | screen manifest | none | | Antigravity CLI | screen manifest | none | | Kiro CLI | screen manifest | none | +| Maki | screen manifest | none | Detected but less thoroughly tested: Gemini CLI and Cline. Unsupported agents still run normally as terminal processes. They just may not get rich state unless you add an integration or report state over the socket API. @@ -113,17 +114,22 @@ Targets accept terminal IDs, unique agent names, detected or reported agent labe ## Custom status labels -Integrations can report a visual status label without changing semantic state. +Integrations report lifecycle state as semantic state only. Add display customization separately with pane metadata tokens. ```bash herdr pane report-agent w1:p1 \ --source custom:indexer \ --agent docs-bot \ - --state working \ - --custom-status indexing + --state working + +herdr pane report-metadata w1:p1 \ + --source custom:indexer-display \ + --token summary=indexing ``` -`state` controls waits, notifications, and rollups. `custom-status` is only display text. +`state` controls waits, notifications, and rollups. The `summary` token is display-only and can be used as `$summary` in an Agent sidebar row. + +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 diff --git a/website/src/content/docs/cli-reference.mdx b/website/src/content/docs/cli-reference.mdx index 81fe4dce..a7c11d92 100644 --- a/website/src/content/docs/cli-reference.mdx +++ b/website/src/content/docs/cli-reference.mdx @@ -120,6 +120,7 @@ herdr workspace create [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [ herdr workspace get herdr workspace focus herdr workspace rename