diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/next/CHANGELOG.md | 3 | ||||
| -rw-r--r-- | docs/next/README.md | 38 | ||||
| -rw-r--r-- | docs/next/product-announcement.json | 5 | ||||
| -rw-r--r-- | docs/next/website/src/content/docs/concepts.mdx | 6 | ||||
| -rw-r--r-- | docs/next/website/src/content/docs/configuration.mdx | 85 | ||||
| -rw-r--r-- | docs/next/website/src/content/docs/quick-start.mdx | 16 |
6 files changed, 88 insertions, 65 deletions
diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md index 36188a11..6d7094a6 100644 --- a/docs/next/CHANGELOG.md +++ b/docs/next/CHANGELOG.md @@ -3,6 +3,8 @@ ## Unreleased ### Added +- Added keybinding v2 with explicit `prefix+...` syntax, array bindings per action, configurable prefix-mode pane focus, tab switching, and direct modified chords for users who opt in. (#154) +- Added `herdr config reset-keys` to back up `config.toml` and remove custom keybindings so built-in v2 defaults apply on restart or config reload. (#154) - Added an integrations tab in settings and first-run onboarding so users can install recommended agent integrations from inside Herdr. - Added `terminal.default_shell` to choose the executable used for new interactive panes. When unset, Herdr still falls back to `$SHELL`, then `/bin/sh`. (#196) - Added native Kiro CLI detection with idle and working state heuristics. (#185) @@ -11,6 +13,7 @@ - Remote clients now bridge local clipboard images into the remote pane by staging them as temporary image files and pasting the remote path, so Claude Code image paste works over `herdr --remote`. (#205) ### Breaking Changes +- Keybindings now use explicit trigger syntax: `prefix+c` means prefix mode, while `ctrl+alt+c` is direct. Bare printable direct bindings such as `new_tab = "c"` are rejected with diagnostics because they intercept normal typing. The default keymap now gives tmux-style tab actions to `prefix+c`, `prefix+n`/`prefix+p`, and `prefix+1..9`, uses `prefix+w` for workspace navigation, and moves pane focus to `prefix+h/j/k/l`. (#154) - The client/server protocol is now version 8. Stop and restart any running v0.5.12 server before attaching with this release. ## [0.5.12] - 2026-05-19 diff --git a/docs/next/README.md b/docs/next/README.md index f32fbca9..402d7d4e 100644 --- a/docs/next/README.md +++ b/docs/next/README.md @@ -53,10 +53,10 @@ herdr session stop work herdr session delete side-project ``` -1. press `n` to create a workspace +1. press `ctrl+b`, then `shift+n` to create a workspace 2. run an agent in the root pane -3. press `ctrl+b` to enter navigate mode -4. use `v` or `-` to split panes, or `c` to create a new tab +3. press `ctrl+b`, then `w` to open workspace navigation +4. use `ctrl+b`, then `v` or `minus` to split panes, or `ctrl+b`, then `c` to create a new tab 5. watch the sidebar for blocked, working, and done states on first run herdr opens a short onboarding flow. after that, restored sessions land in terminal mode; fresh sessions start in **navigate mode**. @@ -201,32 +201,38 @@ see the [integrations docs](https://herdr.dev/docs/integrations/) for setup deta ## keybindings -press `ctrl+b` to enter navigate mode. +press `ctrl+b` to enter prefix mode. default actions are prefix-first and tmux-like: | key | action | |-----|--------| -| `n` | new workspace | -| `shift+n` | rename workspace | -| `shift+d` | close workspace | -| `c` | new tab | -| `v` / `-` | split pane | -| `x` | close pane | -| `b` | toggle sidebar | -| `f` | zoom pane | -| `r` | resize mode | -| `q` | detach (quit client) | +| `prefix+c` | new tab | +| `prefix+n` / `prefix+p` | next / previous tab | +| `prefix+1..9` | switch tab | +| `prefix+w` | workspace navigation | +| `prefix+shift+n` | new workspace | +| `prefix+shift+w` | rename workspace | +| `prefix+shift+d` | close workspace | +| `prefix+h/j/k/l` | focus pane | +| `prefix+v` / `prefix+minus` | split pane | +| `prefix+x` | close pane | +| `prefix+b` | toggle sidebar | +| `prefix+z` | zoom pane | +| `prefix+r` | resize mode | +| `prefix+d` | detach (quit client) | resize mode: `h`/`l` resize width, `j`/`k` resize height, `esc` exit. -custom command keybindings can launch detached shell helpers or temporary panes from prefix mode: +custom command keybindings can launch detached shell helpers or temporary panes: ```toml [[keys.command]] -key = "g" +key = "prefix+g" type = "pane" # "shell" or "pane" command = "lazygit" ``` +if you have old custom keybindings and want the new defaults, run `herdr config reset-keys`. herdr backs up `config.toml`, removes only keybinding config, and uses built-in v2 defaults after restart or config reload. + mouse is supported throughout. full reference: [configuration docs](https://herdr.dev/docs/configuration/). ## configuration diff --git a/docs/next/product-announcement.json b/docs/next/product-announcement.json new file mode 100644 index 00000000..f76743f2 --- /dev/null +++ b/docs/next/product-announcement.json @@ -0,0 +1,5 @@ +{ + "id": "keybinding-v2", + "title": "Keybind Refactor", + "body": "### Breaking change: keybinding syntax changed\n\nHerdr now uses explicit tmux-style keybindings. If you want the new defaults, run `herdr config reset-keys`. Herdr backs up your config first, removes only keybinding settings, and preserves non-key settings.\n\nBefore, many keybinding values implicitly meant \"after pressing the prefix\". Now the binding must say that directly:\n\n- Before: `new_tab = \"c\"`\n- After: `new_tab = \"prefix+c\"`\n\nBindings without `prefix+` are direct terminal-mode shortcuts. Direct shortcuts can intercept keys before shells, editors, tmux, SSH, and terminal apps receive them. If your current config has old bare keybindings, Herdr may warn about them or disable unsafe bindings.\n\nThe new defaults are prefix-first:\n\n- `prefix+c` creates a tab\n- `prefix+n` / `prefix+p` switch tabs\n- `prefix+1..9` switches tabs\n- `prefix+h/j/k/l` focuses panes\n- `prefix+w` opens workspace navigation\n\nPlease read the updated keybinding docs before customizing again:\n\nhttps://herdr.dev/docs/configuration/" +} diff --git a/docs/next/website/src/content/docs/concepts.mdx b/docs/next/website/src/content/docs/concepts.mdx index ea77ac20..b1a7908f 100644 --- a/docs/next/website/src/content/docs/concepts.mdx +++ b/docs/next/website/src/content/docs/concepts.mdx @@ -67,11 +67,11 @@ herdr server stop ## Modes -Herdr has terminal mode and navigate mode. +Herdr has terminal mode, prefix mode, and navigate mode. -Terminal mode sends keys to the focused pane. Navigate mode sends keys to Herdr. +Terminal mode sends keys to the focused pane. Prefix mode waits for one Herdr action after the prefix key. Navigate mode is the persistent workspace navigation surface. -Press the prefix key, default `ctrl+b`, to enter navigate mode. Use navigate mode to create workspaces, split panes, switch tabs, resize, open menus, or detach. +Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation. ## Mouse UI diff --git a/docs/next/website/src/content/docs/configuration.mdx b/docs/next/website/src/content/docs/configuration.mdx index 317dc4d2..bc43d4f0 100644 --- a/docs/next/website/src/content/docs/configuration.mdx +++ b/docs/next/website/src/content/docs/configuration.mdx @@ -58,72 +58,79 @@ When unset or empty, Herdr uses `$SHELL`, then `/bin/sh`. This is an executable ## Keybindings -Herdr has a prefix mode similar to tmux. The default prefix is `ctrl+b`. +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. A small keybinding override looks like this: ```toml [keys] prefix = "ctrl+b" -new_workspace = "n" -rename_workspace = "shift+n" -close_workspace = "shift+d" -new_tab = "c" -split_vertical = "v" -split_horizontal = "-" -close_pane = "x" -zoom = "f" -resize_mode = "r" -toggle_sidebar = "b" +new_tab = "prefix+c" +next_tab = "prefix+n" +previous_tab = "prefix+p" +focus_pane_left = "prefix+h" +split_horizontal = "prefix+minus" ``` -Optional actions are unset by default. Bind them when you want direct shortcuts: +The default keymap is prefix-first and avoids direct shortcuts that can steal input from shells, editors, tmux, or terminal apps. Common defaults include: ```toml [keys] -detach = "q" -reload_config = "R" -open_notification_target = "o" -previous_workspace = "H" -next_workspace = "L" -previous_agent = "A" -next_agent = "D" -previous_tab = "J" -next_tab = "K" -rename_tab = "T" -close_tab = "W" -rename_pane = "p" -edit_scrollback = "e" -focus_pane_left = "h" -focus_pane_down = "j" -focus_pane_up = "k" -focus_pane_right = "l" +workspace_picker = "prefix+w" +new_workspace = "prefix+shift+n" +rename_workspace = "prefix+shift+w" +close_workspace = "prefix+shift+d" +new_tab = "prefix+c" +previous_tab = "prefix+p" +next_tab = "prefix+n" +switch_tab = "prefix+1..9" +rename_tab = "prefix+shift+t" +close_tab = "prefix+shift+x" +focus_pane_left = "prefix+h" +focus_pane_down = "prefix+j" +focus_pane_up = "prefix+k" +focus_pane_right = "prefix+l" +split_vertical = "prefix+v" +split_horizontal = "prefix+minus" +close_pane = "prefix+x" +zoom = "prefix+z" +resize_mode = "prefix+r" +toggle_sidebar = "prefix+b" ``` -Use the full default config to see every available action. +Optional actions are unset by default. Bind them with `prefix+` for prefix-mode behavior, or with an explicit modified chord when you intentionally want a direct shortcut: -Key strings accept plain keys, modifier combinations such as `ctrl+a`, `shift+n`, `alt+1`, `cmd+k`, and special keys such as `enter`, `tab`, `esc`, `left`, `right`, `up`, and `down`. Plain keys, `ctrl+letter`, Escape, Tab, Enter, and function keys are the most reliable. Alt, Cmd/Super, and punctuation with modifiers depend on your terminal and tmux settings. +```toml +[keys] +previous_workspace = "prefix+shift+left" +next_workspace = "prefix+shift+right" +next_tab = ["prefix+n", "ctrl+alt+]"] +``` + +Key strings accept plain keys, modifier combinations such as `ctrl+a`, `shift+n`, `alt+1`, `cmd+k`, and special keys such as `enter`, `tab`, `esc`, `left`, `right`, `up`, and `down`. Named punctuation such as `minus`, `comma`, `ampersand`, `plus`, and `backtick` is also accepted. Plain direct printable keys such as `n` are unsafe because they intercept typing; use `prefix+n` unless you intentionally want a direct binding. Alt, Cmd/Super, and punctuation with modifiers depend on your terminal and tmux settings. + +If you have old custom keybindings and want the new defaults, run `herdr config reset-keys`. Herdr backs up `config.toml`, removes `[keys]` and `[[keys.command]]`, and uses built-in v2 defaults after restart or `herdr server reload-config`. ## Indexed jumps -Indexed keybindings let you jump directly to visible positions. +Indexed keybindings use `1..9` in normal keybinding fields: ```toml -[keys.indexed] -workspaces = "ctrl+shift" -tabs = "ctrl" -agents = "alt" +[keys] +switch_tab = "prefix+1..9" +switch_workspace = "prefix+shift+1..9" +focus_agent = "prefix+alt+1..9" ``` -These expand over number keys 1 through 9. For example, `tabs = "ctrl"` makes `ctrl+1` through `ctrl+9` switch tabs. +The legacy `[keys.indexed]` table is still parsed for compatibility, but new configs should prefer the explicit action fields. ## Custom command keybindings -Custom prefix-mode commands can run shell helpers from inside Herdr. +Custom commands use the same keybinding syntax. ```toml [[keys.command]] -key = "g" +key = "prefix+g" type = "pane" command = "lazygit" ``` diff --git a/docs/next/website/src/content/docs/quick-start.mdx b/docs/next/website/src/content/docs/quick-start.mdx index fddef6b8..9e2452a7 100644 --- a/docs/next/website/src/content/docs/quick-start.mdx +++ b/docs/next/website/src/content/docs/quick-start.mdx @@ -29,19 +29,21 @@ pi Herdr detects supported agents automatically. The sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle`. -## Navigate +## Keyboard control -Press `ctrl+b` to enter navigate mode. +Press `ctrl+b` to enter prefix mode, then press an action key. Common actions: | Action | Key | | --- | --- | -| Split right | `v` | -| Split down | `-` | -| New tab | `c` | -| New workspace | `n` | -| Detach client | `q` | +| Split right | `prefix+v` | +| Split down | `prefix+minus` | +| New tab | `prefix+c` | +| Next / previous tab | `prefix+n` / `prefix+p` | +| Workspace navigation | `prefix+w` | +| New workspace | `prefix+shift+n` | +| Detach client | `prefix+d` | After detaching, run `herdr` again to reattach to the same session. |