diff options
Diffstat (limited to 'website/src/content/docs/configuration.mdx')
| -rw-r--r-- | website/src/content/docs/configuration.mdx | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/website/src/content/docs/configuration.mdx b/website/src/content/docs/configuration.mdx index 9df7e41d..72dc610c 100644 --- a/website/src/content/docs/configuration.mdx +++ b/website/src/content/docs/configuration.mdx @@ -56,6 +56,23 @@ default_shell = "nu" When unset or empty, Herdr uses `$SHELL`, then `/bin/sh`. This is an executable name or path, not a shell command line. Existing panes keep their current shell until they are recreated. Command panes still run through `/bin/sh -c`; detached custom command keybindings use Herdr's existing `/bin/sh -lc` path. +## Worktrees + +Set the root directory Herdr uses for Git worktree checkouts created from the sidebar: + +```toml +[worktrees] +directory = "~/.herdr/worktrees" +``` + +Herdr creates checkouts under `<directory>/<repo>/<branch-slug>`. For sibling-style checkouts, set this to a directory such as `~/Projects/herdr-worktrees`. + +Worktree actions are available from Git workspace rows. `New worktree` creates a branch and checkout, opens it as a new Herdr workspace, and groups it under the source workspace. `Open worktree...` lists existing Git worktree checkouts for that repo; choosing an already-open checkout focuses it, and choosing a closed checkout opens it in the same group. + +Grouped worktrees still behave like normal Herdr workspaces: they can be focused, renamed, closed, and contain their own tabs and panes. The parent row is the original workspace. Closing the parent row closes the whole Herdr group, but it does not delete checkout folders or branches. + +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. + ## 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. @@ -79,6 +96,7 @@ The default keymap is prefix-first and avoids direct shortcuts that can steal in detach = "prefix+q" workspace_picker = "prefix+w" new_workspace = "prefix+shift+n" +new_worktree = "prefix+shift+g" rename_workspace = "prefix+shift+w" close_workspace = "prefix+shift+d" new_tab = "prefix+c" @@ -105,6 +123,8 @@ Optional actions are unset by default. Bind them with `prefix+` for prefix-mode [keys] previous_workspace = "prefix+shift+left" next_workspace = "prefix+shift+right" +open_worktree = "prefix+shift+o" +remove_worktree = "prefix+alt+d" next_tab = ["prefix+n", "ctrl+alt+]"] ``` @@ -183,6 +203,7 @@ sidebar_width = 32 sidebar_min_width = 18 sidebar_max_width = 36 mouse_capture = true +mouse_scroll_lines = 3 confirm_close = true prompt_new_tab_name = true show_agent_labels_on_pane_borders = false @@ -198,6 +219,8 @@ accent = "cyan" Set `mouse_capture = false` if you want your terminal to handle normal clicks, such as command-clicking URLs. +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. + Set `show_agent_labels_on_pane_borders = true` if you want detected agent labels in split pane borders when no manual pane label is set. ## Notifications @@ -284,6 +307,29 @@ kitty_graphics = false Leave this off unless you are testing terminal image behavior. +## IME cursor tracking + +When the focused pane hides its cursor and paints its own — common in AI-agent TUIs like Claude Code, pi, and codex — macOS native input methods stop tracking the candidate window position because the outer terminal stops reporting the cursor. + +Set `reveal_hidden_cursor_for_cjk_ime = true` to expose the focused pane's cursor anchor to the outer terminal regardless of the pane's `?25l` request: + +```toml +[experimental] +reveal_hidden_cursor_for_cjk_ime = false +cjk_ime_agents = [] +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`. 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`. + +Hot-reloads through the existing `[experimental]` block. + +The trade-off when enabled: an extra hardware cursor is visible in the outer terminal for apps that hide the cursor without painting a replacement (vim normal mode, etc.). Pair the reveal with `cjk_ime_agents` to scope it to specific TUIs. + ## Environment variables | Variable | Purpose | |