From 5f27bc37e588efddd5c293c4a05bfccf0c87a16a Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Fri, 15 May 2026 18:47:18 +0300 Subject: [PATCH] docs: draft changelog for next release --- .pi/docs/CONFIGURATION.md | 15 ++++++-- .pi/docs/INTEGRATIONS.md | 5 +-- .pi/docs/README.md | 2 +- CHANGELOG.md | 18 ++++++++++ CONFIGURATION.md | 74 +++++++++++++++++++++++++++++++-------- INTEGRATIONS.md | 5 +-- README.md | 2 +- 7 files changed, 97 insertions(+), 24 deletions(-) diff --git a/.pi/docs/CONFIGURATION.md b/.pi/docs/CONFIGURATION.md index 4336185e..61e316d1 100644 --- a/.pi/docs/CONFIGURATION.md +++ b/.pi/docs/CONFIGURATION.md @@ -190,7 +190,7 @@ command = "notify-send herdr 'custom command ran'" ## theme -herdr ships with 10 built-in color themes. set one in config: +herdr ships with 17 built-in color themes. set one in config: ```toml [theme] @@ -202,14 +202,21 @@ name = "tokyo-night" | name | description | |------|-------------| | `catppuccin` | soft pastel mocha palette (default) | +| `catppuccin-latte` | light catppuccin palette | | `tokyo-night` | blue-purple aesthetic | +| `tokyo-night-day` | light tokyo night palette | | `dracula` | purple/pink/green classic | | `nord` | frosty scandinavian blues | | `gruvbox` | warm retro browns/oranges | -| `one-dark` | atom's beloved palette | -| `solarized` | ethan schoonover's classic | +| `gruvbox-light` | light gruvbox palette | +| `one-dark` | atom's beloved dark palette | +| `one-light` | atom's light palette | +| `solarized` | ethan schoonover's classic dark palette | +| `solarized-light` | ethan schoonover's classic light palette | | `kanagawa` | hokusai-inspired | +| `kanagawa-lotus` | light kanagawa palette | | `rose-pine` | muted, elegant | +| `rose-pine-dawn` | light rosé pine palette | | `vesper` | high-contrast monochrome with peach and mint accents | theme names are flexible: `tokyo-night`, `tokyonight`, and `tokyo_night` all work. @@ -261,6 +268,7 @@ for `panel_bg`, you can also use `reset`, `default`, `none`, or `transparent` to ```toml [ui] sidebar_width = 26 +mouse_capture = true confirm_close = true show_agent_labels_on_pane_borders = false agent_panel_scope = "all" @@ -272,6 +280,7 @@ accent = "cyan" | option | default | description | |--------|---------|-------------| | `sidebar_width` | `26` | base sidebar width before auto-scaling | +| `mouse_capture` | `true` | capture mouse input for Herdr's mouse UI; set false to let the terminal handle normal clicks while still forwarding mouse to pane apps that request it | | `confirm_close` | `true` | ask before closing a workspace | | `show_agent_labels_on_pane_borders` | `false` | show detected/reported agent labels in split pane borders when no manual pane name is set | | `agent_panel_scope` | `all` | sidebar agent list scope: `current` or `all` | diff --git a/.pi/docs/INTEGRATIONS.md b/.pi/docs/INTEGRATIONS.md index 2489f619..ec4e4884 100644 --- a/.pi/docs/INTEGRATIONS.md +++ b/.pi/docs/INTEGRATIONS.md @@ -126,7 +126,8 @@ this: - writes the hook script to `~/.codex/herdr-agent-state.sh` - updates `~/.codex/hooks.json` -- ensures `codex_hooks = true` in `~/.codex/config.toml` +- ensures `hooks = true` under `[features]` in `~/.codex/config.toml` +- migrates the deprecated top-level `[features] codex_hooks = true` setting to `hooks = true` bundled source: [`src/integration/assets/codex/herdr-agent-state.sh`](./src/integration/assets/codex/herdr-agent-state.sh) @@ -156,7 +157,7 @@ this: - removes herdr-owned hook entries from `~/.codex/hooks.json` - intentionally leaves `~/.codex/config.toml` alone -that last point is deliberate: herdr does **not** try to guess whether `codex_hooks = true` is still needed for some other codex hook setup. +that last point is deliberate: herdr does **not** try to guess whether `hooks = true` is still needed for some other codex hook setup. ## opencode diff --git a/.pi/docs/README.md b/.pi/docs/README.md index 05346b81..1b5ed7fa 100644 --- a/.pi/docs/README.md +++ b/.pi/docs/README.md @@ -131,7 +131,7 @@ not a gui window, not a web dashboard, not electron. herdr runs inside whatever - **tabs** — first-class in the socket api and cli - **mouse-native** — click panes/tabs/workspaces/agents, drag borders, select text to copy, right-click menus; not keyboard-only - **notifications** — sounds and toasts for background events; tab-aware suppression -- **10 built-in themes** — catppuccin (default), tokyo night, dracula, nord, gruvbox, one dark, solarized, kanagawa, rosé pine, vesper +- **17 built-in themes** — catppuccin, 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 after full restart ## agents can use herdr too diff --git a/CHANGELOG.md b/CHANGELOG.md index 36e21d6e..ce2e0f90 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,24 @@ ## Unreleased +### Added +- Added experimental Kitty graphics rendering for local panes and attached clients behind `experimental.kitty_graphics`, including support for larger graphics frames. +- Added `ui.toast.delivery = "system"` for OS-level background notifications, using `notify-send` on Linux and `terminal-notifier` or `osascript` on macOS. +- Added light variants for Catppuccin, Tokyo Night, Gruvbox, One, Solarized, Kanagawa, and Rosé Pine themes. +- Added `ui.mouse_capture = false` for tmux-style mouse behavior, letting the terminal handle normal clicks while still forwarding mouse input to pane apps that request it. + +### Changed +- Moved experimental settings into `[experimental]`. + +### Fixed +- PageUp and PageDown now scroll Herdr pane scrollback for normal panes while still forwarding keys to full-screen or mouse-reporting apps. +- Enhanced tilde key sequences now parse correctly, improving compatibility with terminals that emit them. +- `herdr integration install codex` now enables the current Codex `[features] hooks = true` flag and migrates the deprecated top-level `codex_hooks` flag. + +### Breaking Changes +- `advanced.allow_nested` has moved to `experimental.allow_nested`; update configs that allow nested Herdr launches. +- The client/server protocol is now version 5. Stop and restart any running v0.5.8 server before attaching with this release. + ## [0.5.8] - 2026-05-12 ### Added diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 0bee5925..61e316d1 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -44,12 +44,13 @@ Reloadable now: - `ui.agent_panel_scope` - `ui.toast.delivery` - server-side `ui.sound` policy; attached thin clients refresh local sound config after a successful sound-policy change +- `experimental.kitty_graphics` - `advanced.scrollback_limit_bytes` for panes created after reload - `ui.sidebar_width` as the default width; current width updates only while it is still config-owned Startup-only or special-case: - `onboarding` does not reopen onboarding during reload -- `advanced.allow_nested` is checked before launch and needs a restart +- `experimental.allow_nested` is checked before launch and needs a restart - existing pane scrollback buffers are not resized during reload - terminal notifications and sounds are client-local side effects and are sent to the foreground attached client @@ -189,7 +190,7 @@ command = "notify-send herdr 'custom command ran'" ## theme -herdr ships with 10 built-in color themes. set one in config: +herdr ships with 17 built-in color themes. set one in config: ```toml [theme] @@ -201,14 +202,21 @@ name = "tokyo-night" | name | description | |------|-------------| | `catppuccin` | soft pastel mocha palette (default) | +| `catppuccin-latte` | light catppuccin palette | | `tokyo-night` | blue-purple aesthetic | +| `tokyo-night-day` | light tokyo night palette | | `dracula` | purple/pink/green classic | | `nord` | frosty scandinavian blues | | `gruvbox` | warm retro browns/oranges | -| `one-dark` | atom's beloved palette | -| `solarized` | ethan schoonover's classic | +| `gruvbox-light` | light gruvbox palette | +| `one-dark` | atom's beloved dark palette | +| `one-light` | atom's light palette | +| `solarized` | ethan schoonover's classic dark palette | +| `solarized-light` | ethan schoonover's classic light palette | | `kanagawa` | hokusai-inspired | +| `kanagawa-lotus` | light kanagawa palette | | `rose-pine` | muted, elegant | +| `rose-pine-dawn` | light rosé pine palette | | `vesper` | high-contrast monochrome with peach and mint accents | theme names are flexible: `tokyo-night`, `tokyonight`, and `tokyo_night` all work. @@ -260,6 +268,7 @@ for `panel_bg`, you can also use `reset`, `default`, `none`, or `transparent` to ```toml [ui] sidebar_width = 26 +mouse_capture = true confirm_close = true show_agent_labels_on_pane_borders = false agent_panel_scope = "all" @@ -271,6 +280,7 @@ accent = "cyan" | option | default | description | |--------|---------|-------------| | `sidebar_width` | `26` | base sidebar width before auto-scaling | +| `mouse_capture` | `true` | capture mouse input for Herdr's mouse UI; set false to let the terminal handle normal clicks while still forwarding mouse to pane apps that request it | | `confirm_close` | `true` | ask before closing a workspace | | `show_agent_labels_on_pane_borders` | `false` | show detected/reported agent labels in split pane borders when no manual pane name is set | | `agent_panel_scope` | `all` | sidebar agent list scope: `current` or `all` | @@ -299,7 +309,20 @@ delivery = "off" available values: - `off` — disable popup notifications - `herdr` — show top-right in-app toasts -- `terminal` — ask the outer terminal to show a desktop notification +- `terminal` — ask the outer terminal to show a desktop notification. some terminals suppress foreground notifications, including ghostty on macos. +- `system` — ask the os notification service directly. on macos, herdr uses `terminal-notifier` when available and falls back to built-in `osascript`. on linux, `system` requires `notify-send`. + +### macos system notifications + +for best macos support, install `terminal-notifier`: + +```sh +brew install terminal-notifier +``` + +when `terminal-notifier` is installed, herdr tries to focus the hosting terminal when a notification is clicked. click-to-return is supported for detected ghostty, iterm2, wezterm, kitty, alacritty, and terminal.app sessions. + +without `terminal-notifier`, herdr falls back to built-in `osascript`. this still shows a macos notification, but clicking the notification may focus the apple script runner instead of returning to your terminal. compatibility note: - older configs may still use `ui.toast.enabled = true|false` @@ -312,7 +335,9 @@ current behavior: - shown for background agent events like `needs attention` and `finished` - suppression is tab-aware: the active tab stays quiet, but background tabs in the same workspace can still notify - `terminal` delivery is best-effort and depends on terminal support -- currently targets terminals such as Ghostty, Kitty, iTerm2, and WezTerm +- `system` delivery is best-effort and depends on the os helper being available +- macos `system` delivery prefers `terminal-notifier` when present and falls back to `osascript` +- currently targets terminals such as ghostty, kitty, iterm2, and wezterm - inside tmux, herdr wraps notification escapes with tmux passthrough ## sound @@ -350,11 +375,37 @@ available agent keys: - `droid` - `amp` +## experimental + +```toml +[experimental] +allow_nested = false +kitty_graphics = false +``` + +### options + +| option | default | description | +|--------|---------|-------------| +| `experimental.allow_nested` | `false` | allow launching herdr from inside a herdr-managed pane | +| `experimental.kitty_graphics` | `false` | enable experimental local Kitty graphics rendering for attached clients | + +### nested launches + +By default, herdr blocks nested launches when `HERDR_ENV=1` is already present. + +Set `allow_nested = true` only for debugging or intentionally nested setups. + +### Kitty graphics + +`kitty_graphics` enables experimental local Kitty graphics rendering for attached clients. + +It requires a Kitty graphics-compatible outer terminal. + ## advanced ```toml [advanced] -allow_nested = false scrollback_limit_bytes = 10000000 ``` @@ -362,15 +413,8 @@ scrollback_limit_bytes = 10000000 | option | default | description | |--------|---------|-------------| -| `advanced.allow_nested` | `false` | allow launching herdr from inside a herdr-managed pane | | `advanced.scrollback_limit_bytes` | `10000000` | maximum scrollback buffer size in bytes retained per pane terminal | -### nested launches - -By default, herdr blocks nested launches when `HERDR_ENV=1` is already present. - -Set `allow_nested = true` only for debugging or intentionally nested setups. - ### scrollback `scrollback_limit_bytes` limits retained terminal scrollback per pane. @@ -379,7 +423,7 @@ The default matches Ghostty's `scrollback-limit` value. Set `scrollback_limit_bytes = 0` to disable pane scrollback entirely. -The old `advanced.scrollback_lines` key is still accepted as a compatibility alias, but it uses the same byte-based value. +The legacy `scrollback_lines` key is still accepted inside `[advanced]`, but it uses the same byte-based value. ## environment variables diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md index 2489f619..ec4e4884 100644 --- a/INTEGRATIONS.md +++ b/INTEGRATIONS.md @@ -126,7 +126,8 @@ this: - writes the hook script to `~/.codex/herdr-agent-state.sh` - updates `~/.codex/hooks.json` -- ensures `codex_hooks = true` in `~/.codex/config.toml` +- ensures `hooks = true` under `[features]` in `~/.codex/config.toml` +- migrates the deprecated top-level `[features] codex_hooks = true` setting to `hooks = true` bundled source: [`src/integration/assets/codex/herdr-agent-state.sh`](./src/integration/assets/codex/herdr-agent-state.sh) @@ -156,7 +157,7 @@ this: - removes herdr-owned hook entries from `~/.codex/hooks.json` - intentionally leaves `~/.codex/config.toml` alone -that last point is deliberate: herdr does **not** try to guess whether `codex_hooks = true` is still needed for some other codex hook setup. +that last point is deliberate: herdr does **not** try to guess whether `hooks = true` is still needed for some other codex hook setup. ## opencode diff --git a/README.md b/README.md index 05346b81..1b5ed7fa 100644 --- a/README.md +++ b/README.md @@ -131,7 +131,7 @@ not a gui window, not a web dashboard, not electron. herdr runs inside whatever - **tabs** — first-class in the socket api and cli - **mouse-native** — click panes/tabs/workspaces/agents, drag borders, select text to copy, right-click menus; not keyboard-only - **notifications** — sounds and toasts for background events; tab-aware suppression -- **10 built-in themes** — catppuccin (default), tokyo night, dracula, nord, gruvbox, one dark, solarized, kanagawa, rosé pine, vesper +- **17 built-in themes** — catppuccin, 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 after full restart ## agents can use herdr too