From 9f6ac06b76e76808dffa58efddcbf997dbae7985 Mon Sep 17 00:00:00 2001 From: Wangshuyi Date: Thu, 13 Aug 2026 12:17:47 +0800 Subject: [PATCH] Document herdr-gui features --- FEATURES.md | 291 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 10 +- USAGE.md | 78 ++++++++------ 3 files changed, 347 insertions(+), 32 deletions(-) create mode 100644 FEATURES.md diff --git a/FEATURES.md b/FEATURES.md new file mode 100644 index 0000000..b3e8380 --- /dev/null +++ b/FEATURES.md @@ -0,0 +1,291 @@ +# herdr-gui Features + +herdr-gui is a browser and PWA client for a running +[Herdr](https://herdr.dev) server. It keeps Herdr's workspace, tab, pane, and +agent model, while adding repository tools, session inspection, mobile controls, +and operational features around it. + +For installation and deployment, see [README.md](./README.md). For the detailed +Chinese setup guide, see [USAGE.md](./USAGE.md). + +## Workspace, Tab, and Pane Navigation + +- Browse all Herdr workspaces and their recognized agents from one sidebar. +- Create, rename, focus, pin, and close workspaces. +- Group linked Git worktrees under their parent repository workspace. Groups can + be collapsed, while individual workspaces or worktrees can be pinned to the + top. Pin and collapse preferences are stored in the current browser. +- Create, rename, switch, and close tabs in the focused workspace. +- Split the active pane right or down, resize pane boundaries with the pointer, + focus neighboring panes, zoom a pane, and close panes. +- Use the searchable command menu (`Cmd/Ctrl+K`) for workspace, worktree, file, + tab, pane, and agent actions. Entering a workspace-relative or absolute file + path opens that file directly. + +### Recent Pane Switcher + +`Ctrl+Tab` opens a most-recently-used switcher that can jump between panes in +other tabs and workspaces. It keeps the 12 most recently focused live panes and +also includes panes in the current layout. Each entry shows its workspace, tab +or working directory, and Agent icon/status when available. + +- Press `Ctrl+Tab` to start on the previously used pane. +- Keep holding `Ctrl` and press `Tab` to move forward. +- Use `Ctrl+Shift+Tab` to move backward. +- `Up` and `Down` also move through the list. +- Release `Ctrl` or press `Enter` to switch. +- Press `Esc` to cancel. + +Closed panes are removed from the history automatically. + +## Full Browser Terminal + +- Render Herdr's server-side terminal stream at the browser's current rows and + columns, including split-pane layouts. +- Send normal terminal input, modified Enter sequences, and common macOS + line-editing shortcuts. +- Scroll terminal history with a mouse wheel, trackpad, touch gesture, + `Page Up`/`Page Down`, or half-page `Alt/Option+Page Up`/`Page Down`. +- Paste multiline text through terminal paste handling. +- Paste a clipboard image to upload it on the Herdr host and insert the resulting + path into the terminal. This also works through `--ssh-host`. +- Relay OSC 52 clipboard writes from local or remote terminal applications to + the initiating browser. +- `Cmd/Ctrl`-click HTTP(S) links to open them safely in a new tab. +- `Cmd/Ctrl`-click workspace-relative or absolute file paths in terminal output + to preview text, Markdown, or images without leaving the terminal. +- Preserve IME composition and rapid CJK punctuation input. + +## Agent Awareness and Session Inspection + +Herdr reports recognized agents and their state, and herdr-gui projects that +information across the workspace tree, pane switcher, command menu, and Agent +panel. + +- See Agent identity and status such as working, blocked, done, or idle. +- Focus an Agent's pane from the sidebar, command menu, recent pane switcher, or + a browser task-completion notification. +- Open a message-history drawer beside the active terminal. Assistant messages + can be included or hidden. +- Inspect turn count, token usage, update time, session ID, session file, and + other session details. +- Open Session Inspector in Timeline, ATIF, or raw transcript mode, with search + for ATIF and raw content. +- Export the original session file or the normalized ATIF trajectory. + +Session inspection currently supports Codex, Claude, Kimi, Grok Build, and Pi. +It requires a readable session record; for agents that rely on Herdr integration, +the UI shows the integration command when session metadata is unavailable. +Session paths reported by Herdr are read from the remote host when `--ssh-host` +is active, and Pi session IDs support remote lookup. Other ID/directory fallback +searches, including Grok Build discovery, remain local and may not resolve a +remote session unless its transcript is also locally accessible. + +## Git Worktree Lifecycle + +herdr-gui adds a repository-scoped lifecycle view around Herdr workspaces: + +- Create a linked worktree from the latest fetched `origin/main` without + modifying the source workspace's current branch or dirty files. +- Discover and open existing linked worktrees. +- View all repository checkouts, their paths, open/closed state, branch status, + and uncommitted-change counts. +- Focus open worktrees, run `git pull`, and enable automatic branch updates per + checkout. +- Remove linked worktrees with confirmation, hook execution, process cleanup, + and recovery that preserves residual files when safe removal is not possible. +- Manage the lifecycle from a workspace context menu or from the command menu by + searching for `worktree lifecycle`. + +### Paseo Worktree Hooks + +herdr-gui understands the repository-local +[Paseo worktree hook](https://paseo.sh/docs/worktrees) format in `paseo.json`. +Add commands under `worktree`: + +```json +{ + "worktree": { + "setup": "bun install", + "opened": "./scripts/worktree-opened.sh", + "teardown": "./scripts/worktree-teardown.sh", + "removed": "./scripts/worktree-removed.sh" + } +} +``` + +| Paseo hook | When herdr-gui runs it | Working directory | +| --- | --- | --- | +| `setup` | After a new linked worktree has been created and opened | New worktree | +| `opened` | After an existing linked worktree has been opened | Opened worktree | +| `teardown` | Before a linked worktree is removed | Worktree being removed | +| `removed` | After removal finishes | Source checkout | + +For `setup`, `opened`, and `teardown`, herdr-gui first looks for `paseo.json` in +the target checkout and falls back to the source checkout only when the target +has no `paseo.json`. The first existing file wins. After removal, the target no +longer exists, so `removed` normally uses the source checkout's configuration. + +Commands run through `sh -c`. The following variables are available: + +| Variable | Value | +| --- | --- | +| `PASEO_HOOK` | `setup`, `opened`, `teardown`, or `removed` | +| `PASEO_CHECKOUT_PATH` | Target worktree path, including the former path for `removed` | +| `PASEO_SOURCE_CHECKOUT_PATH` | Parent/source checkout path when known | +| `HERDR_GUI_HOOK_EVENT` | `worktree.created`, `worktree.opened`, `worktree.before_remove`, or `worktree.removed` | +| `HERDR_GUI_HOOK_CHECKOUT_PATH` | Same target path exposed under a herdr-gui-specific name | +| `HERDR_GUI_HOOK_SOURCE_CHECKOUT_PATH` | Same source path exposed under a herdr-gui-specific name | + +Operation notices show the hook outcome and bounded diagnostic output; failures +can include the exit code, stderr, or an error. A failed `teardown` hook stops +removal so the repository can clean up or disable the hook before retrying. +Other hooks are not transactional: a failed `setup` or `opened` hook does not +undo the create/open operation, and a failed `removed` hook cannot restore an +already removed worktree. + +Hooks are enabled by default for every repository. They can be disabled per +repository from **Worktree hooks** or **Worktree Lifecycle**; the dialogs also +show which `paseo.json` and commands were detected. + +With `--ssh-host`, configuration is read and commands are executed on the remote +host. Hooks are trusted repository code and are not sandboxed; review a +repository's `paseo.json` before creating, opening, or removing its worktrees. + +### Automatic Branch Updates + +Automatic branch updates periodically fetch `origin/main` and merge it into an +enabled workspace's current branch. The default interval is 10 minutes, and the +current interval and last result are visible in the UI. + +For safety, herdr-gui skips a run when the checkout is dirty or on a detached +HEAD. It verifies that the branch, HEAD, and worktree did not change while the +fetch was running. A conflicting merge is aborted automatically. Updates run +only while the workspace is open in the current herdr-gui connection. + +Use **Menu → Automatic branch updates**, a workspace context menu, or Worktree +Lifecycle to manage saved per-checkout settings. + +## File Explorer and Preview + +- Browse a cached, expandable workspace file tree and optionally include hidden + files. +- Search files that have been loaded into the tree. +- See Git status badges on changed files and directories. +- Preview text with line numbers, syntax highlighting, and `Cmd/Ctrl+F` search. +- Render Markdown with a Raw/Rendered toggle. +- Preview common image formats; unsupported binary files remain download-only. +- Drag files onto the workspace root or a directory to upload them. +- Download files directly or directories as workspace-scoped `.tar.gz` + archives. +- Copy absolute paths and delete files or directories with confirmation. +- Open the file action menu with right-click on desktop or long-press on touch + devices. + +File operations and previews work for both local and SSH-backed workspaces. + +## Diff Viewer + +- Browse changed files as a directory tree with staged, unstaged, untracked, + conflicted, and branch-diff badges plus added/deleted line counts. +- Switch between the current working tree and the current branch **Against + main**. +- View all changed files in repository order. +- Use side-by-side or unified diffs on desktop; mobile uses a unified layout. +- Toggle wrapping independently on desktop and mobile. +- Search the rendered diff with `Cmd/Ctrl+F`, Enter/Shift+Enter navigation, or + the previous/next controls. +- Syntax-highlight textual diffs and preview changed image files. +- Jump from a diff section to the corresponding File Explorer preview. + +The selected scope, view mode, wrapping preference, and recent selection are +preserved in the browser. + +## Mobile and PWA + +- Responsive workspace, terminal, File Explorer, and Diff Viewer layouts with + mobile-safe viewport and keyboard handling. +- A floating terminal panel with two rows of configurable key actions. +- A direct `2×8` shortcut editor: empty slots retain their position in the + editor but are compacted out of the runtime panel. +- Up to four optional terminal side buttons. +- Shortcut actions for control keys, arrows, Enter variants, and full/half-page + terminal scrolling. +- A mobile pane switcher for tabs containing multiple panes. +- A bundled glyph-only Nerd Font fallback for common terminal icons. +- Installable as a standalone PWA from iOS/iPadOS Safari, macOS Safari, Chrome, + or Edge. PWA mode removes browser chrome but still requires a reachable + herdr-gui server; it does not provide offline access. + +Mobile shortcut layouts and appearance preferences are stored in the current +browser and do not change Herdr server configuration. + +## Remote, Multi-Client, and Operations + +- Connect to a remote Herdr with `--ssh-host`; herdr-gui automatically forwards + both the control and terminal-render Unix sockets over SSH. +- Apply file operations, image paste, Git operations, and Paseo hooks on the + same remote host, with remote session inspection subject to the metadata + resolution limits described above. +- Connect multiple browsers to one bridge and receive pushed Herdr events in + each client. +- Pause or resume the current browser connection, see the connected-client + count, or pause the other clients. +- Enable browser task-completion notifications that return directly to the + relevant pane. +- Choose light/dark themes and persistent accent colors. +- Install and manage a systemd or launchd user service from the CLI. +- Check for herdr-gui releases and perform a checksum-verified, one-click binary + update when running a standalone binary under a supported supervisor. +- Use `/health` or `/healthz` for service probes. + +Loopback access is unauthenticated by default. Non-loopback binds use a generated +login token unless a fixed password is configured. The built-in authentication +does not provide TLS, rate limiting, multi-user authorization, or sandboxing; +see [SECURITY.md](./SECURITY.md) before exposing the service. + +## Keyboard Shortcut Reference + +The in-app reference is available from **Menu → Keyboard shortcuts**. + +### Global + +| Shortcut | Action | +| --- | --- | +| `Cmd/Ctrl+K` | Open or close the command menu | +| `Ctrl+Tab` / `Ctrl+Shift+Tab` | Open and navigate the recent Pane switcher | +| `Cmd+B` | Toggle the desktop sidebar | +| `Cmd+T` | Create a tab in the focused workspace | +| `Cmd+W` | Close the focused tab | +| `Cmd+Option+Left` / `Cmd+Option+Right` | Switch tabs, wrapping at either end | +| `Ctrl+1` … `Ctrl+9` | Switch to a numbered tab in the focused workspace | +| `Ctrl+Shift+W` | Open Workspaces | +| `Cmd/Ctrl+Shift+E` | Toggle File Explorer | +| `Ctrl+Shift+G` | Open Diff Viewer | +| `Esc` | Dismiss the current menu, dialog, notification, or update banner | + +A host browser can reserve shortcuts such as `Cmd+T` and `Cmd+W`; they are most +reliable in an installed PWA or another standalone/webview host. + +### Terminal + +| Shortcut | Action | +| --- | --- | +| `Page Up` / `Page Down` | Scroll terminal history by one page | +| `Alt/Option+Page Up` / `Alt/Option+Page Down` | Scroll terminal history by half a page | +| `Shift+Enter` | Send a multiline Enter sequence | +| `Alt+Enter` | Send an Alt-modified Enter sequence | +| `Cmd+Left` / `Cmd+Up` | Move to the beginning of the current input line | +| `Cmd+Right` / `Cmd+Down` | Move to the end of the current input line | +| `Cmd+Backspace` | Delete to the beginning of the current input line | +| `Cmd+V` on Apple, `Ctrl+V` elsewhere | Paste text or images | +| `Cmd/Ctrl+Click` an HTTP(S) link | Open the link | +| `Cmd/Ctrl+Click` a file path | Preview the workspace file | +| `Cmd/Ctrl+Shift+H` | Toggle Agent message history for the active terminal | + +### Preview and Diff + +| Shortcut | Action | +| --- | --- | +| `Cmd/Ctrl+F` | Search the visible raw file preview or Diff Viewer | +| `Enter` / `Shift+Enter` in Diff search | Move to the next/previous match | diff --git a/README.md b/README.md index 0e249cf..1a74595 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,9 @@ running Herdr server through its local socket API and gives you a browser dashboard: workspace/tab/pane tree, a spatial layout view, agent status, and basic pane control (send text, read output, split/close/zoom). +See [FEATURES.md](./FEATURES.md) for a complete feature tour, keyboard +shortcuts, and repository-local Paseo worktree hooks. + 中文使用说明见 [USAGE.md](./USAGE.md)。长期运行可直接使用 [`herdr-gui service`](#run-as-a-user-service) 安装 systemd/launchd 用户服务。 @@ -324,9 +327,10 @@ Unix-socket forwards for both the control and terminal-render sockets: ./herdr-gui --ssh-host user@host ``` -`--ssh-host` also makes pasted images and worktree-hook config writes happen on -the remote host. If you need custom local socket paths, pass -`--socket-path ` and `--client-socket-path ` explicitly; those flags +`--ssh-host` also makes pasted images, workspace file operations, and +repository worktree-hook execution happen on the remote host. If you need custom +local socket paths, pass `--socket-path ` and +`--client-socket-path ` explicitly; those flags override the automatic tunnel paths. ## Stack diff --git a/USAGE.md b/USAGE.md index c9a1264..475837b 100644 --- a/USAGE.md +++ b/USAGE.md @@ -359,10 +359,14 @@ launchctl bootout "gui/$(id -u)/dev.herdr.herdr-gui" 顶部右侧的 `Menu` 用来查看和修改配置，包括： -- 当前连接状态。 -- 当前访问 URL。 -- 当前 Herdr socket。 -- Worktree Hooks 状态和配置路径。 +- 明暗主题、强调色和任务完成通知。 +- 移动端 terminal 快捷键和自动 branch 更新。 +- Changelog、键盘快捷键和 herdr-gui 更新。 +- 当前连接状态、client 数量、访问 URL、Herdr socket、server 版本和协议。 +- 暂停或恢复当前 client，以及暂停其他已连接 client。 + +Worktree Hooks 属于仓库配置，请从 workspace 右键菜单、命令菜单或 +`Worktree Lifecycle` 打开。 ## Terminal @@ -389,37 +393,53 @@ terminal 区域支持鼠标滚轮和触摸滑动。移动端默认显示两行 ## Worktree Hooks -打开顶部 `Menu`，点击 `Edit worktree hooks` 可以配置 worktree 事件 hook。 - -当前支持三个事件： - -- `Created`：对应 `worktree.created` -- `Opened`：对应 `worktree.opened` -- `Removed`：对应 `worktree.removed` - -每个输入框填写一段 shell 命令。保存后，herdr-gui 会生成一个 Herdr plugin： - -```text -~/.config/herdr-gui/plugins/worktree-hooks -``` - -如果当前使用 `--ssh-host` 连接远程 Herdr，plugin 会写到远程机器的同一路径。 +herdr-gui 直接读取仓库里的 Paseo `paseo.json`，不会生成 Herdr plugin，也不会在 +界面中修改 hook 命令。Hook 对每个仓库默认启用；可以从 workspace 右键菜单选择 +`Worktree hooks...`，或在 `Worktree Lifecycle` 中打开 `Hook details`，查看当前 +仓库检测到的配置并按仓库禁用或重新启用。完整功能说明见 +[FEATURES.md](./FEATURES.md#paseo-worktree-hooks)。 示例： -```bash -echo "worktree event: $PWD" >> /tmp/herdr-worktree-hooks.log +```json +{ + "worktree": { + "setup": "bun install", + "opened": "./scripts/worktree-opened.sh", + "teardown": "./scripts/worktree-teardown.sh", + "removed": "./scripts/worktree-removed.sh" + } +} ``` -Hook 命令由 Herdr 在事件发生时执行。命令会通过 `sh -c` 运行，所以可以使用普通 shell 语法。 +当前支持四个 Paseo hook： -`worktree.created` 和 `worktree.opened` hook 会在目标 worktree 根目录执行，因此可以使用相对路径： - -```bash -bash ./scripts/setup-worktree-env.sh -``` - -创建 worktree 后，如果配置了 `worktree.created` hook，界面会显示 hook 的执行状态；失败时会展示 exit code、stderr 或 error，成功时会展示最多一部分 stdout。 +| Hook | 执行时机 | 工作目录 | +| --- | --- | --- | +| `setup` | 新 linked worktree 创建并打开之后 | 新 worktree | +| `opened` | 已有 linked worktree 打开之后 | 打开的 worktree | +| `teardown` | 删除 linked worktree 之前 | 即将删除的 worktree | +| `removed` | 删除完成之后 | source checkout | + +命令通过 `sh -c` 执行，可以使用普通 shell 语法。`setup`、`opened` 和 +`teardown` 会先读取目标 checkout 的 `paseo.json`；只有目标中不存在该文件时， +才回退到 source checkout。命令可以使用以下环境变量： + +- `PASEO_HOOK` +- `PASEO_CHECKOUT_PATH` +- `PASEO_SOURCE_CHECKOUT_PATH` +- `HERDR_GUI_HOOK_EVENT` +- `HERDR_GUI_HOOK_CHECKOUT_PATH` +- `HERDR_GUI_HOOK_SOURCE_CHECKOUT_PATH` + +操作通知会展示 hook 结果和长度受限的诊断信息；失败时可能包含 exit code、 +stderr 或 error。`teardown` 失败时会停止删除，修复命令或临时禁用该仓库的 hook +后才能重试。其他 hook 不会回滚已经完成的生命周期操作：`setup` 或 `opened` +失败不会撤销创建/打开，`removed` 失败也无法恢复已删除的 worktree。 + +如果使用 `--ssh-host`，`paseo.json` 会从远程仓库读取，hook 也在远程机器执行。 +Hook 属于受信任的仓库代码，不会运行在 sandbox 中；执行 worktree 操作前应先检查 +仓库的 `paseo.json`。 ## 开发模式