Initial import: chezmoi source for Omarchy (Hyprland)

Imported from prdlk/dotfiles master (efdd827), which supersedes the omarchy
branch (3031416). Drops the Umbriel, Noctalia, niri, CachyOS, macOS, and Blume
docs-site layers; docs/ is plain Markdown.

docs/terminal/README.md

@@ -0,0 +1,19 @@
+# Terminal
+
+Terminal emulators and multiplexers configured by the dotfiles.
+
+kitty is the primary terminal. It runs in three modes: plain kitty (kitty owns splits and tabs), a tmux host, and a herdr host. Ghostty is a tmux-only terminal: every window attaches to tmux, and its `ctrl+shift` chords drive tmux.
+
+| Page | Source | What it covers |
+| --- | --- | --- |
+| [kitty](kitty.md) | external repo via `.chezmoiexternals/kitty.toml` | Main config, host configs (tmux, herdr, goliath), kittens, custom tab bar |
+| [Ghostty](ghostty.md) | external repo via `.chezmoiexternals/ghostty.toml` | tmux-only terminal: ctrl+shift chords → tmux, themes |
+| [tmux](tmux.md) | external repo via `.chezmoiexternals/tmux.toml` | Prefix, bindings, kitty-style tabs with Nerd Font icons, resurrect/continuum persistence |
+| [herdr](herdr.md) | external repo via `.chezmoiexternals/herdr.toml`, plus `dot_config/herdr-nvim/` | Agent-aware multiplexer: keys, theme, plugins, Claude hook |
+
+## Shared conventions
+
+- Font: VictorMono Nerd Font everywhere.
+- Background opacity `0.9`, no window decorations; the compositor provides blur.
+- Prefix `ctrl+b` in tmux and herdr. kitty and Ghostty translate chords into the prefix byte `\x02` plus a key, so the same physical shortcut works across hosts.
+- `ctrl+h/j/k/l` moves between panes across nvim, kitty, tmux, and herdr (vim-aware handoff at every layer).

docs/terminal/ghostty.md

@@ -0,0 +1,97 @@
+# Ghostty
+
+Ghostty as a tmux-only terminal — every window attaches to tmux, and ctrl+shift chords drive tmux.
+
+Ghostty is the default terminal and only a [tmux](tmux.md) client. tmux owns tabs (windows), splits (panes), sessions, and persistence. Ghostty draws the text and handles the clipboard and font size.
+
+It is the default everywhere a desktop picks a terminal: the first entry of `~/.config/xdg-terminals.list` (`dot_config/xdg-terminals.list`, desktop roles only) is what `xdg-terminal-exec` and `omarchy-launch-terminal` launch.
+
+| | |
+| --- | --- |
+| Source | [prdlk/ghostty](https://github.com/prdlk/ghostty) via `.chezmoiexternals/ghostty.toml`: `config`, `themes/` |
+| Target | `~/.config/ghostty/` |
+| Install | `ghostty` in `packages.arch.pacman` |
+
+`~/.config/ghostty` is a `git-repo` external checkout, not chezmoi-managed contents; edit it in place and commit and push from there.
+
+`config` holds every setting, ending in `theme = noctalia`. That theme file is generated, not shipped (the ghostty repo's `.gitignore` excludes it), so without its generator ghostty finds no such theme; select `theme = cherry-blossom` instead on this setup.
+
+## Options
+
+| Option | Value |
+| --- | --- |
+| `font-family` / `font-size` | `IoskeleyMonoTerm Nerd Font Mono` / `11` |
+| `adjust-cell-height` | `20%` (line height) |
+| `background-opacity` / `background-blur` | `0.9` / `true` |
+| `window-decoration` | `false`; `gtk-titlebar = false` |
+| `window-padding-x/y` | `0` |
+| `cursor-style` | `underline`, blinking |
+| `scrollback-limit` | `3023` (tmux keeps the real scrollback: `history-limit 50000`) |
+| `mouse-hide-while-typing` | `true` |
+| `copy-on-select` | `false` |
+| `confirm-close-surface` | `false` |
+| `link-url` / `link-previews` | `true` / `true`. Under tmux (`mouse on`) tmux receives the click, so open links with `ctrl+shift+click`; tmux opens OSC 8 links on a plain `ctrl+click` |
+| `app-notifications` | `no-clipboard-copy,no-config-reload` |
+| `quit-after-last-window-closed` | `false`, delay `5m` |
+| `command` | `shell:$HOME/.local/bin/ghostty-tmux` (see [Sessions](#sessions)) |
+| `shell-integration` | `detect`, features `cursor,sudo,title,no-cursor` |
+| `gtk-single-instance` | `true` |
+
+## Sessions
+
+Every Ghostty window gets its own tmux session; no two windows mirror the same one. `~/.local/bin/ghostty-tmux` (source `dot_local/bin/executable_ghostty-tmux`) runs for each new window:
+
+1. If a detached session exists (left by a closed window, or restored by continuum after a reboot), it attaches to the oldest one, by session id. Background task sessions from `pj-palette` (`@pj_task` set, named `<session>:<task>`) are never reclaimed.
+2. Otherwise it starts a new session.
+
+Before starting tmux, the script puts mise's shims on `PATH`. A server started from a desktop-launched Ghostty therefore finds the tools tmux plugins shell out to: bun for the palette, fzf, and zoxide.
+
+The window title is the tmux session name (`set-titles-string '#S'`), so the compositor's window groups list one entry per session. tmux's tab bar keeps its own fixed cyberdream colors, so it does not match Ghostty's background exactly.
+
+Closing a window only detaches its session; the shells keep running in the tmux server. In tmux, `detach-on-destroy no-detached` means killing a session moves the window to a *detached* session, or closes the window if there is none, so it never lands on another window's session. Across reboots, tmux-continuum saves every 10 minutes. The first Ghostty window starts the server, and that triggers continuum's restore. See [tmux](tmux.md#persistence).
+
+## Keybindings
+
+`keybind = clear` comes first and drops every Ghostty default: tabs, splits, `alt+N` goto_tab, and `ctrl+alt+arrow` goto_split. Those chords then reach tmux, which binds `alt+1…9` and `ctrl+alt+arrows` itself. `ctrl+h/j/k/l` also pass straight through to tmux's vim-aware pane navigation, which hands off to and from nvim's splits (see [tmux](tmux.md#keybindings)). Each `ctrl+shift` chord sends tmux's prefix, `ctrl+b` (`\x02`), followed by a key.
+
+| Key | Ghostty action |
+| --- | --- |
+| `ctrl+shift+c` / `ctrl+shift+v` | Copy / paste |
+| `ctrl+plus` / `ctrl+minus` / `ctrl+zero` | Font size +1 / -1 / reset |
+| `ctrl+shift+.` | Reload Ghostty config |
+| `shift+enter` | Sends `ESC[13;2u` (CSI-u Shift+Enter), which tmux passes through to the pane, so coding agents such as omp and Claude Code insert a newline instead of submitting. Not `\n`: that is `ctrl+j`, tmux's pane-down key |
+| `ctrl+space`, `ctrl+backspace` | Sends NUL (tmux `C-Space`): opens the [tmux command palette](tmux.md#command-palette) |
+
+| Key | Sends | tmux action |
+| --- | --- | --- |
+| `ctrl+shift+t` | `prefix c` | New window (tab) in pane cwd |
+| `ctrl+shift+p` / `ctrl+shift+space` | `prefix t` | Project Tasks palette (pj: install, dev, sync, make, every project task) |
+| `ctrl+shift+f` | `prefix y` | Yazi in a new window, pane cwd |
+| `ctrl+shift+e` | `prefix e` | Neovim in a new window, pane cwd |
+| `ctrl+shift+g` | `prefix g` | Lazygit in a 90% popup, pane cwd |
+| `ctrl+shift+a` | `prefix a` | Toggle omp in a background-session popup (`<session>:omp`), pane cwd |
+| `ctrl+shift+w` | `prefix k` | Kill window (close tab) |
+| `ctrl+shift+r` | `prefix r` | Rename window |
+| `ctrl+tab` / `ctrl+page_down` / `ctrl+shift+right` / `ctrl+shift+k` | `prefix n` | Next window |
+| `ctrl+shift+tab` / `ctrl+page_up` / `ctrl+shift+left` / `ctrl+shift+h` | `prefix p` | Previous window |
+| `ctrl+shift+l` | `prefix v` | Split right |
+| `ctrl+shift+j` | `prefix h` | Split below |
+| `ctrl+shift+o` / `super+enter` | `prefix o` | Sessions palette: switch session or window, or create one through zoxide |
+| `ctrl+shift+x` | `prefix x` | Kill pane |
+| `ctrl+shift+enter` / `ctrl+shift+z` | `prefix z` | Zoom pane |
+| `ctrl+shift+page_up` | `prefix [` | Copy mode |
+| `ctrl+shift+/` | `prefix ?` | Keybinding help popup |
+| `ctrl+shift+alt+,` | `prefix q` | Reload tmux config |
+| `ctrl+shift+n` | `prefix C` | New session |
+| `ctrl+shift+s` | `prefix s` | Session/window tree |
+| `ctrl+shift+q` | `prefix d` | Detach (closes the Ghostty window; the session lives on) |
+
+## Themes
+
+| Theme | Notes |
+| --- | --- |
+| `noctalia` | Generated, not shipped: the file is written from the active palette (currently the custom `CherryBlossom` palette: background `#222120`, foreground `#dcc1b7`, salmon cursor `#cf716f`) and excluded by the ghostty repo's `.gitignore`. It exists only on machines that generate it. |
+| `cherry-blossom` | Static copy of the `CherryBlossom` palette (same colors as the generated `noctalia` theme). Always present; set `theme = cherry-blossom` to use it. |
+| `cyberdream` | Upstream `extras/ghostty/cyberdream` from [cyberdream.nvim](https://github.com/scottmckendry/cyberdream.nvim), the palette shared with tmux, nvim, yazi, and television. |
+| `ii-auto` | Auto-generated by the ii wallpaper theming system; not meant to be edited. |
+| `koda-dark` / `koda-light` | Koda palettes with `bold-is-bright = true`. |

docs/terminal/herdr.md

@@ -0,0 +1,91 @@
+# herdr
+
+herdr, an agent-aware terminal multiplexer, with its keys, theme, plugins and Claude Code hook.
+
+herdr is a terminal multiplexer with workspaces, tabs and panes, a sidebar, a prefix key (`ctrl+b`), and a plugin system. It tracks coding agents running in its panes: agent-state colors, next/previous agent keys, and an integration that reports Claude Code sessions to it.
+
+| | |
+| --- | --- |
+| Source | [prdlk/herdr](https://github.com/prdlk/herdr) via `.chezmoiexternals/herdr.toml` (`~/.config/herdr/`); `dot_config/herdr-nvim/config.toml` |
+| Target | `~/.config/herdr/`, `~/.config/herdr-nvim/config.toml` |
+| Install | Not in `packages.yaml`; updated by topgrade (`herdr update`) |
+| Launch | kitty `super+a` (see [kitty](kitty.md)) |
+
+## config.toml
+
+`onboarding = false`.
+
+### UI and theme
+
+| Setting | Value |
+| --- | --- |
+| `ui.pane_borders`, `ui.pane_outer_borders` | `false` (panes separated by gaps only) |
+| `ui.prompt_new_tab_name` | `false` |
+| `ui.accent` | `#5ea1ff` |
+| `ui.status_indicators` | `symbols` |
+| `ui.toast.delivery` | `system` |
+| `theme.name` | `terminal`, `auto_switch = false` |
+| `theme.custom.panel_bg` | `reset` (keeps kitty's translucency and compositor blur) |
+| `sidebar_bg` / `active_row_bg` / `selection_bg` | `#16181a` / `#1e2124` / `#3c4048` |
+| `accent` / `surface_dim` | `#243348` / `#5ea1ff` (active tab plate matches kitty's tab bar) |
+| Agent-state colors | green `#5eff6c`, yellow `#f1ff5e`, red `#ff6e5e`, peach `#ffbd5e`, mauve `#bd5eff` |
+| `experimental.kitty_graphics` | `true`; `pane_history = false` |
+| `switch_ascii_input_source_in_prefix` | `true` |
+
+These are cyberdream colors.
+
+### Keys
+
+| Key | Action |
+| --- | --- |
+| `prefix %` | Split vertical |
+| `prefix "` | Split horizontal |
+| `prefix d` | Detach |
+| `prefix s` | Workspace picker |
+| `prefix shift+s` | Settings |
+| `k` / `j` | Move up / down in the workspace picker (pane up/down in navigate mode unbound) |
+| `prefix .` / `prefix ,` | Next / previous agent |
+| `prefix j` / `prefix k` | Next / previous workspace |
+| `prefix up/down/left/right` | Focus pane |
+| `ctrl+h/j/k/l` | `vim-herdr-navigation` left/down/up/right |
+| `prefix e` | `chmarax.herdr-nvim.toggle` (nvim sidebar) |
+| `prefix o` | `chmarax.herdr-nvim.pick-file` (open file from agent output) |
+| `prefix t` | `switchboard.menu` |
+| `prefix shift+p` | `switchboard.commands` |
+| `prefix shift+l` | `switchboard.git` |
+| `prefix shift+k` | `switchboard.projects` |
+| `prefix y` | Open `official.browser` plugin in a right split |
+| `prefix shift+o` | Open `official.browser` as an overlay |
+
+## Plugins
+
+`plugins.json` is herdr's plugin registry. `.plugins.lock` is committed empty. `plugins/config/official.browser/` and `plugins/config/vim-herdr-navigation/` hold placeholder `.keep` files for per-plugin config. `plugins/github/`, where herdr installs plugin checkouts, is gitignored in the repo.
+
+| Plugin | Description (from its manifest) |
+| --- | --- |
+| `chmarax.herdr-nvim` | Full-height nvim sidebar with agent annotations |
+| `herdr-automatic-rename` | Names tabs after the foreground program, adds 1–9 jump numbers |
+| `io.github.salemsayed.omaherd` | Tells the Omarchy bar when an agent changes state |
+| `official.browser` | Open and inspect real browser pages from herdr |
+| `oh-my-opencode-slim` | OpenCode agent orchestration with a herdr adapter |
+| `persiyanov.reviewr` | Review agent-written diffs beside the chat |
+| `rjyo.window-title-sync` | Syncs the outer terminal title to the focused workspace, tab and agent |
+| `switchboard` | Command palette: projects, commands, ports, git, clone, settings |
+| `vim-herdr-navigation` | Vim-aware `ctrl+h/j/k/l` pane movement |
+
+[fish](../shell/fish.md) sources `herdr-automatic-rename`'s `shell/hook.fish` if present.
+
+## herdr-nvim
+
+**~/.config/herdr-nvim/config.toml**
+
+```toml
+[sidebar]
+position = "left"
+```
+
+The nvim sidebar opens to the left of existing panes (default is right).
+
+## herdr/kitty.conf
+
+A legacy kitty config kept in the herdr folder. It runs `tmux new-session -A -s main`, listens on `unix:@mykitty`, includes `current-theme.conf`, maps `super`/`alt` keys to tmux prefix bytes, and has a copy of an older `tmux.conf` appended. The active herdr host is `~/.config/kitty/herdr.conf`.

docs/terminal/kitty.md

@@ -0,0 +1,221 @@
+# kitty
+
+kitty configuration, host variants, custom kittens and the Python tab bar.
+
+GPU terminal emulator and the primary terminal on every role.
+
+| | |
+| --- | --- |
+| Source | [prdlk/kitty](https://github.com/prdlk/kitty) via `.chezmoiexternals/kitty.toml` |
+| Target | `~/.config/kitty/` |
+| Install | `kitty` in `.chezmoidata/packages.yaml` (pacman), plus `ttf-victor-mono-nerd` for the font |
+
+```text
+~/.config/kitty/
+  kitty.conf
+  tmux.conf
+  herdr.conf
+  goliath.conf
+  ssh.conf
+  current-theme.conf
+  tab_bar.py
+  pass_keys.py
+  day_session.py
+  navigate_kitty.py
+  select_tab.py
+  switchtab.py
+  window_titler.py
+  themes/
+    cyberdream.conf
+    koda-dark.conf
+    koda-light.conf
+```
+
+`~/.config/kitty` is a `git-repo` external checkout, not chezmoi-managed contents; edit it in place and commit and push from there. The repo's `.gitignore` excludes `__pycache__/` next to `tab_bar.py`.
+
+## Theme and colors
+
+Every config ends with:
+
+**~/.config/kitty/kitty.conf**
+
+```conf
+include ~/.local/state/omarchy/current/theme/kitty.conf
+```
+
+Colors come from the active Omarchy theme; it is included last so it wins. `current-theme.conf` is a symlink committed in the repo, pointing at `themes/cyberdream.conf`. Only the legacy `~/.config/herdr/kitty.conf` ([prdlk/herdr](https://github.com/prdlk/herdr)) includes `current-theme.conf`; the main config does not. `themes/` holds `cyberdream`, `koda-dark`, and `koda-light` color files.
+
+## kitty.conf
+
+| Option | Value |
+| --- | --- |
+| `font_family` | `VictorMono Nerd Font`, then overridden in the `BEGIN_KITTY_FONTS` block to `family="VictorMono Nerd Font Mono"`; bold/italic `auto` |
+| `window_padding_width` | `8` |
+| `hide_window_decorations` | `yes` |
+| `background_opacity` | `0.9` |
+| `cursor_trail` | `10`, `cursor_trail_start_threshold 0`, `cursor_trail_decay 0.01 0.05` |
+| `cursor_blink_interval` | `0` (set to 1, then overridden) |
+| `copy_on_select` | `auto` |
+| `strip_trailing_spaces` | `smart` |
+| `confirm_os_window_close` | `0` |
+| `allow_remote_control` | `socket-only` |
+| `listen_on` | `unix:@kitty-{kitty_pid}` |
+| `enabled_layouts` | `splits:split_axis=vertical,stack` |
+| Tab bar | `powerline`, `slanted`, centered, top edge, always shown (`tab_bar_min_tabs 1`, so the stack-layout indicator is visible with one tab), `tab_title_template "{custom}"` |
+
+> [!NOTE]
+> Transparency uses kitty's own alpha, so text stays opaque. This alpha is also what lets the compositor blur the window: Hyprland enables blur globally and opts out every window except terminal classes.
+
+The socket also exports `KITTY_LISTEN_ON` into each pane. nvim reads it to know kitty owns the panes and hands `ctrl+h/j/k/l` back to kitty at an edge.
+
+### Launch aliases
+
+| Alias | Expands to |
+| --- | --- |
+| `launch_mn` | `launch --cwd=current --type=overlay-main` |
+| `launch_os` | `launch --cwd=current --type=os-window` |
+| `launch_ov` | `launch --cwd=current --type=overlay` |
+| `launch_tb` | `launch --cwd=current --type=tab` |
+| `launch_hs` | `launch --cwd=current --location=hsplit --bias=30` |
+| `launch_vs` | `launch --cwd=current --location=vsplit --bias=40` |
+| `launch_vs50` | `launch --cwd=current --location=vsplit --bias=50` |
+
+### Keybindings
+
+| Key | Action |
+| --- | --- |
+| `super+n` | Vertical split 50/50 (`launch_vs50`) |
+| `super+z` | Toggle `stack` layout (zoom); the tab title gains a layers icon and pane count (`nf-md-layers 3`) while other panes are hidden |
+| `ctrl+shift+t`, `super+enter` | New tab in current cwd |
+| `ctrl+space`, `ctrl+shift+j` | Horizontal split, 30% (`launch_hs`) |
+| `ctrl+enter`, `ctrl+shift+l` | Vertical split, 40% (`launch_vs`) |
+| `ctrl+shift+space` | New OS window |
+| `ctrl+shift+h` / `ctrl+shift+k` | Previous / next tab |
+| `ctrl+shift+g` | `lazygit` in an overlay |
+| `ctrl+shift+f` | `yazi` in a new tab |
+| `ctrl+shift+e` | `nvim` in a 50/50 vertical split |
+| `ctrl+shift+p` | `atuin-pick` in a horizontal split |
+| `super+t` | Spawn a separate kitty (`--class=kitty-tmux`, `--config ~/.config/kitty/tmux.conf`) |
+| `super+a` | Spawn a separate kitty (`--class=kitty-herdr`, `--config ~/.config/kitty/herdr.conf`) |
+| `ctrl+shift+c` / `ctrl+shift+v` | Copy / paste clipboard |
+| `alt+q w e r t y u i o` | Go to tab 1–9 |
+| `ctrl+h/j/k/l` | `pass_keys.py`: move to neighbor window left/bottom/top/right, or pass the key through |
+| `super+left` / `super+right` | Resize window narrower / wider |
+| `super+up` / `super+down` | Resize window taller / shorter (by 3) |
+
+The tmux and herdr hosts are separate kitty processes because `launch` cannot take `--config`.
+
+### Daily sessions
+
+`day_session.py` keeps one kitty session file per day, grouped by week:
+
+```text
+~/.local/share/kitty-sessions/<monday YYYY-MM-DD>/<day YYYY-MM-DD>.kitty-session
+~/.local/share/kitty-sessions/<monday YYYY-MM-DD>/<day YYYY-MM-DD>.scrollback/<window key>.ansi
+```
+
+| Directive | Role |
+| --- | --- |
+| `geninclude day_session.py` | Creates today's (empty) session file and emits `startup_session <path>` whenever no running kitty owns today's session. Ownership is an `flock` on `$XDG_RUNTIME_DIR/kitty-day-<day>.kitty-session.lock`, held until that kitty exits, so closing kitty and launching it again always reopens the day, even if other kitties (or yesterday's) are still running. A second concurrent instance starts plain instead of duplicating today's tabs. A kitty started with `--session` for another day never takes the lock. |
+| `watcher day_session.py` | About 1 s after a window opens, closes, resizes or splits, changes focus or finishes a command (catches `cd`), and every 30 s for output from long-running programs, rewrites the session this instance started with. Title changes are ignored so spinners don't trigger saves. Skips the save once the session has no windows, so closing kitty keeps the last good state. |
+
+Earlier days open with the [`kitty-days`](../tools/television.md#kitty-days) tv cable (`tv kitty-days`), each in its own kitty (`kitty --session <file>`). A past day is a read-only snapshot: nothing in that kitty saves it back. Today's file opened that way, while no kitty owns it, becomes the live day again.
+
+Before shutdown or reboot, the `kitty-day-save.service` user unit runs [`kitty-day-save`](../shell/scripts.md#kitty-day-save) under a logind delay inhibitor. On `PrepareForShutdown(true)` it sends `kitten day_session.py flush` to every `@kitty-<pid>` socket: the owning kitty saves at once (all windows are still alive), then skips saves for 60 s so windows dying during the shutdown can't shrink the file. [`30-user-services`](../chezmoi/scripts.md#30-user-services) enables the unit.
+
+What a restored window gets back:
+
+- **Scrollback**: each window carries a `day_scrollback=<key>` user var (kept by kitty's `launch --var`); its history is dumped as ANSI to `<key>.ansi`, minus the idle prompt, and dumps of closed windows are pruned. On restore, the shell runs `cat <key>.ansi` through kitty's shell-integration startup command, so it needs shell integration (fish here). A dump is only written after the shell has drawn a prompt, so a restored window can't overwrite its history before replaying it.
+- **Running program**: saved with `--use-foreground-process` and re-run after the `cat`, so the shell is still there when it exits (`nvim`, `sleep 700`, dev servers). Commands still at shell init when saved (mise/direnv hooks) are ignored. A command is never replayed if any of its words is `rm`, `rmdir`, `mv`, `dd`, `shred`, `truncate`, `mkfs*`, `wipefs`, `fdisk`, `parted`, `sudo`, `doas`, `su`, `run0`, `pkexec`, `kill`, `pkill`, `killall`, `reboot`, `shutdown` or `poweroff` (`NO_REPLAY`).
+- Programs launched as the window's own command (`ctrl+shift+e` nvim, `ctrl+shift+g` lazygit) were already restored by kitty; they have no shell, so no scrollback.
+
+Only windows that belong to the session are saved: `new_tab_with_cwd` and the `--cwd=current` launch aliases join it; `new_os_window` (`ctrl+shift+space`) does not.
+
+## Host configs
+
+### tmux.conf — kitty as a tmux host
+
+Launched by `super+t`. kitty stays a dumb terminal; tmux owns panes, windows and sessions. `listen_on unix:@kitty-tmux`, `tab_bar_style hidden`, `shell kitty-tmux` (a launcher script), and `clear_all_shortcuts yes`, so only the bindings below exist. Prefix byte `\x02` is `ctrl+b`; see [tmux](tmux.md) for what each prefix key does.
+
+| Key | Sends / does |
+| --- | --- |
+| `ctrl+shift+c` / `ctrl+shift+v` | Copy / paste |
+| `ctrl+plus` / `ctrl+minus` / `ctrl+0` | Font size +1 / -1 / reset |
+| `ctrl+shift+alt+,` | Reload kitty config |
+| `ctrl+shift+a` | Spawn a kitty herdr host |
+| `super+t`, `super+enter`, `ctrl+shift+t` | `prefix t` (new window) |
+| `ctrl+shift+h` / `ctrl+shift+k` | `prefix H` / `prefix L` (previous / next window) |
+| `alt+q w e r t y u i o` | `prefix 1`–`9` |
+| `ctrl+shift+j` | `prefix "` (split below) |
+| `ctrl+shift+l`, `ctrl+enter` | `prefix %` (split right) |
+| `ctrl+shift+f` | `prefix z` (zoom) |
+| `ctrl+shift+w`, `super+w` | `prefix x` (kill pane) |
+| `super+left/right/up/down` | `prefix` + `ctrl+arrow` (resize) |
+| `ctrl+shift+g` | `tmux display-popup` 90%×90% running `lazygit` in pane cwd |
+| `ctrl+shift+e` | `tmux new-window` running `nvim` in pane cwd |
+| `ctrl+shift+p` | `tmux split-window -v -l 25%` running `atuin-pick` |
+| `super+n`, `ctrl+shift+space` | New OS window |
+| `super+d` | `prefix d` (detach) |
+
+### herdr.conf — kitty as a herdr host
+
+Launched by `super+a`. Class `kitty-herdr`, `tab_bar_style hidden` (herdr draws its own sidebar and tab strip), `shell herdr` (launches or attaches the persistent session; closing the window detaches). Base appearance matches `kitty.conf`, without a `listen_on`. An uppercase letter after `\x02` is the shift variant. See [herdr](herdr.md).
+
+| Key | Sends / does |
+| --- | --- |
+| `super+c` / `super+v` | Copy / paste |
+| `ctrl+plus` / `ctrl+minus` / `ctrl+0` | Font size +1 / -1 / reset |
+| `ctrl+shift+alt+,` | Reload kitty config |
+| `ctrl+shift+n` | `prefix N` |
+| `super+n` | `prefix G` |
+| `super+t`, `ctrl+shift+t` | `prefix c` |
+| `ctrl+space` | `prefix t` (Switchboard menu) |
+| `super+z` | `prefix z` |
+| `ctrl+tab` / `ctrl+shift+tab` | `prefix .` / `prefix ,` (next / previous agent) |
+| `ctrl+shift+f` | `prefix K` (Switchboard projects) |
+| `ctrl+shift+g` | `prefix L` (Switchboard git) |
+| `ctrl+shift+e` | `prefix e` (herdr-nvim sidebar toggle) |
+| `ctrl+shift+o` | `prefix o` (herdr-nvim pick file) |
+| `ctrl+shift+h` / `ctrl+shift+l` | `prefix p` / `prefix n` |
+| `ctrl+shift+j` / `ctrl+shift+k` | `prefix j` / `prefix k` (next / previous workspace) |
+| `ctrl+shift+w` | `prefix W` |
+| `ctrl+shift+r` | `prefix T` |
+| `ctrl+shift+,` | `prefix S` (herdr settings) |
+| `ctrl+shift+q` | `prefix x` |
+| `ctrl+shift+p` | `prefix P` (Switchboard commands) |
+
+### goliath.conf — remote tmux over mosh
+
+Opens straight into the tmux session `main` on host `goliath` via `mosh goliath -- tmux new-session -A -s main`. `font_size 9.0`, `listen_on unix:@kitty-goliath`, `env MOSH_TITLE_NOPREFIX=1` (drops mosh's `[mosh] ` title prefix), `tab_bar_style hidden`.
+
+> [!WARNING]
+> mosh bootstraps ssh with `-S none`, so non-interactive key auth to goliath must work. It needs mosh on both ends and UDP 60000–61000 open. mosh sets `TERM=xterm-256color`, so kitty-only capabilities such as undercurl are unavailable inside.
+
+| Key | Sends |
+| --- | --- |
+| `super+w` | `prefix x` |
+| `super+t` | `prefix %` |
+| `super+n` | `prefix "` |
+| `super+enter`, `alt+n` | `prefix t` |
+| `alt+h` / `alt+l` | `prefix H` / `prefix L` |
+| `alt+q w e r t y u i o` | `prefix 1`–`9` (`alt+t` is bound twice; the later `prefix 5` wins) |
+| `super+left/right/up/down` | `prefix` + `ctrl+arrow` |
+| `super+d` | `prefix d` |
+
+### ssh.conf
+
+Kitten `ssh` config: for `hostname goliath`, `share_connections yes`.
+
+## Kittens and Python
+
+| File | Purpose |
+| --- | --- |
+| `tab_bar.py` | Provides `draw_title` for `{custom}` in the tab template. Title is `<index> <icon> <label>`: the label is the git repo root name of the tab's cwd (walks up for `.git`), or the file nvim is editing (parsed from nvim's title). Icon comes from the foreground process cmdline (editors, AI agents like claude/omp/opencode/codex, git tools, docker, herdr, tmux, yazi, btop, atuin, ssh, chezmoi, …) with a folder fallback. Labels are elided at 28 chars. In the `stack` layout with more than one pane, ` <nf-md-layers> <panes>` is appended; kitty repaints the tab bar on every layout change. No subprocesses or timers. |
+| `pass_keys.py` | Bound to `ctrl+h/j/k/l`. If the window's foreground process matches `vim`, `nvim`, `fzf`, `tv`, `tmux` or `herdr`, the key is forwarded; otherwise kitty moves to the neighboring window. |
+| `navigate_kitty.py` | No-UI kitten that calls `neighboring_window` with a direction argument; the counterpart nvim can invoke. Not mapped in `kitty.conf`. |
+| `select_tab.py` | Full-screen fuzzy tab picker using `kitty @ ls` data; shows cwds zsh-style. Keys: Up/Down/PgUp/PgDn scroll, Enter selects, typing filters, `ctrl+c`/Esc quits. Not mapped in `kitty.conf`. |
+| `switchtab.py` | Focuses the tab whose `vt` user var matches the argument, or launches one with that var and reorders tabs by `vt`. Not mapped. |
+| `window_titler.py` | Watcher that appends `[<vt> <pty>]` to window titles. Not referenced in `kitty.conf`. |
+| `day_session.py` | Daily sessions: `geninclude` script, global watcher and the `flush` no-UI kitten in one file. See [Daily sessions](#daily-sessions). |
+
+Related: the [tmux](tmux.md) `is_vim` check and herdr's `vim-herdr-navigation` plugin complete the `ctrl+h/j/k/l` chain. Hyprland window rules can match the `kitty`, `kitty-tmux` and `kitty-herdr` app-ids ([Hyprland](../desktop/hyprland.md)).

docs/terminal/tmux.md

@@ -0,0 +1,115 @@
+# tmux
+
+tmux prefix, bindings, kitty-style window tabs with Nerd Font icons, and resurrect/continuum persistence.
+
+Terminal multiplexer. [Ghostty](ghostty.md) runs nothing but tmux, and Ghostty's `ctrl+shift` chords are tmux bindings. tmux is also used through the kitty tmux host and remotely on goliath.
+
+| | |
+| --- | --- |
+| Source | [prdlk/tmux](https://github.com/prdlk/tmux) via `.chezmoiexternals/tmux.toml`: `tmux.conf`, `tmux-nerd-font-window-name.yml`, `tab-label.sh` |
+| Target | `~/.config/tmux/` |
+| Install | `tmux` in `.chezmoidata/packages.yaml` (pacman) |
+
+`~/.config/tmux` is a `git-repo` external checkout, not chezmoi-managed contents; edit it in place and commit and push from there. tpm is a separate `git-repo` external in `.chezmoiexternal.toml`, cloned to `~/.config/tmux/plugins/tpm` inside that checkout when missing. `tmux.conf` ends with `run '~/.config/tmux/plugins/tpm/tpm'`. Plugins installed by tpm (`prefix I`) land next to it; the tmux repo's `.gitignore` excludes `plugins/` and chezmoi ignores them. [prdlk/tmux-palette](https://github.com/prdlk/tmux-palette) (`.chezmoiexternals/tmux-palette.toml`, → `~/.config/tmux-palette/`) holds the [palette](#command-palette) config.
+
+## Options
+
+The prefix is `ctrl+b` (the byte Ghostty's `ctrl+shift` chords send). `ctrl+space` is not a prefix: it opens the [command palette](#command-palette).
+
+| Option | Value |
+| --- | --- |
+| `default-terminal` | `tmux-256color`; `RGB` override for every terminal; `clipboard` and `hyperlinks` (OSC 8) features; `extkeys` for xterm-kitty. Features apply after `tmux kill-server` |
+| `extended-keys` | `on`, format `csi-u` |
+| `base-index` / `pane-base-index` | `1` / `1`; `renumber-windows on` |
+| `status-position` | `top`, `status-interval 5` |
+| `allow-passthrough` / `set-clipboard` / `mouse` / `focus-events` | `on` |
+| `update-environment` | `TERM` and `TERM_PROGRAM` appended, so programs see the outer terminal (Ghostty/kitty) |
+| `mode-keys` | `vi` |
+| `set-titles` | `on`, `#S`: the terminal window title is the session name, so compositor window groups list sessions (one per Ghostty window) instead of `host:window` |
+| `automatic-rename-format` | `#{window_icon} <label>`: Nerd Font icon, then the dynamic label described under [Window tabs](#window-tabs) |
+| `history-limit` | `50000` |
+| `detach-on-destroy` | `no-detached` (killing a session switches only to a detached session, else detaches, so a Ghostty window never lands on another window's session) |
+
+These settings are what [yazi](../tools/yazi.md) needs inside tmux. `allow-passthrough` carries image previews through to the terminal, `set-clipboard` copies paths via OSC 52, and the two environment variables let yazi detect the outer terminal's graphics support. Nothing binds `M-[`: tmux would read the `ESC [` that starts yazi's terminal-query replies as that key and break yazi's capability detection.
+
+## Keybindings
+
+`prefix ?` opens all of them in a popup: `omarchy-menu-tmux-keybindings` on Omarchy machines, `tmux list-keys -N` everywhere else.
+
+| Key | Action |
+| --- | --- |
+| `prefix q` | Reload config |
+| `prefix /` | Copy mode, then search upward |
+| `prefix o` | Sessions palette ([`tmux-sessions`](../shell/scripts.md#tmux-sessions)): fuzzy-find the other sessions, every window of every session, zoxide's and `~/.config`'s directories, and Rename/Kill items per session. Typed text that is not a session starts one by that name in its zoxide match |
+| `prefix t` | Project Tasks palette ([`pj-palette`](../shell/scripts.md#pj-palette)): install/dev/sync/make/compose quick actions plus every `pj` task. One-off tasks run in a full-width bottom split (25% of the window); dev servers and `docker compose up` run in a background `<session>:<tool-and-command>` session shown in a popup (`q` hides, `ctrl-c` asks `y/n` then stops), listed under Running to reopen |
+| `prefix y` / `prefix e` | Yazi / Neovim in a new window in the pane cwd (Ghostty `ctrl+shift+f` / `ctrl+shift+e`) |
+| `prefix g` | Lazygit in a 90% popup in the pane cwd (Ghostty `ctrl+shift+g`) |
+| `prefix a` | omp in a background session `<session>:omp` (pane cwd), shown in a popup docked bottom-right (35% × 60%) and listed in the [omp palette](../shell/scripts.md#pj-palette) and under Running in the tasks palette. In the popup, `ctrl-c` hides it and `ctrl-q` quits omp. Inside any background-task popup, `prefix a` hides it too, so Ghostty `ctrl+shift+a` toggles omp |
+| `prefix h` / `prefix v` | Split below / right, pane cwd |
+| `prefix x` | Kill pane |
+| `S-Enter` (no prefix) | Sends `ESC[13;2u` to the pane unchanged. With `extended-keys on`, tmux would otherwise turn Shift+Enter into plain Enter for apps that never requested extended keys, and coding agents (omp, Claude Code) would submit instead of inserting a newline |
+| `C-MouseDown1Pane` (ctrl+click) | Opens the OSC 8 hyperlink under the mouse (`#{mouse_hyperlink}`) with `xdg-open`; without one, the click goes to the pane. Plain-text URLs: `ctrl+shift+click`, handled by Ghostty |
+| `M-Enter` / `M-S-Enter` / `M-Escape` (no prefix) | Split below / split right / kill pane |
+| `C-h` / `C-j` / `C-k` / `C-l` (no prefix) | Vim-aware pane focus. In an nvim/vim/fzf pane (`@pane-is-vim`, set by smart-splits, or the pane's command), the key goes to nvim. nvim's `config.pane_nav` moves between its own splits and, at its outer edge, runs `tmux select-pane -t $TMUX_PANE`. Elsewhere tmux moves directly. Also bound in copy mode |
+| `prefix C-l` | Send `C-l` (clear screen) |
+| `C-M-arrows` / `C-M-S-arrows` (no prefix) | Focus pane / resize pane by 5 |
+| `prefix c` / `prefix k` / `prefix r` | New window in pane cwd / kill window / rename window |
+| `M-1` … `M-9` (no prefix) | Select window 1–9 |
+| `M-Left` / `M-Right` (no prefix) | Previous / next window |
+| `M-S-Left` / `M-S-Right` (no prefix) | Move window left / right |
+| `prefix C` / `prefix K` / `prefix R` | New / kill / rename session |
+| `prefix P` / `prefix N`, `M-Up` / `M-Down` | Previous / next session |
+| Copy mode `v` / `y` | Begin selection / copy and exit |
+
+## Window tabs
+
+The status line copies kitty's tab bar (`tab_bar_style powerline`, `tab_powerline_style angled`). The current window is an accent-tinted plate with accent text. The other windows use `bg=default` and muted text, so the terminal's transparency shows through them, as with kitty's `tab_bar_background none`. That only works while every `window-status-*-style` stays `default`: inside a tab format, `bg=default` means that style's background, not the terminal's. `tmux.conf` therefore sets all of them explicitly, because a reload never clears a value a removed plugin left behind. As in kitty, a solid arrow leads into the current window and a thin one sits between two inactive windows. The arrow into the current window is a plain `U+E0B0` in `@tab-bg`, the window background. Ghostty draws that glyph as a built-in sprite that fills the whole cell even with `adjust-cell-height`. The session name is an accent pill on the far left (`status-justify left`); its arrow points straight into the first tab, so the pill and tabs read as one chain of arrows. The right side shows `COPY`/`PREFIX`/`ZOOM` flags and the hostname.
+
+Colors are the user options `@tab-bg` (window background: the notch arrow and the session pill's text), `@tab-fg`, `@tab-active-bg`, and `@tab-active-fg`. They are a fixed CherryBlossom palette (the same one Ghostty's `cherry-blossom` theme uses), so the bar looks identical on every machine and does not depend on Omarchy. Active background = accent mixed 20% into background, the same derivation as the kitty tab bar: `#453130` from accent `#cf716f` over `#222120`.
+
+Popups (`prefix g`, `prefix t`, `prefix ?`, tmux-palette) set `popup-style` to `bg=@tab-bg` and `popup-border-style` to `@tab-active-fg` on that background with rounded lines. The explicit background matters under Ghostty: `background-opacity` only applies to cells with the default background, so a default-bg popup shows the pane behind it through the blur.
+
+### Tab labels
+
+Each window reads `<index> <icon> <label>`, updating as you work, the same rule as kitty's `tab_bar.py`:
+
+| Pane runs | Label | Source |
+| --- | --- | --- |
+| `nvim`/`vim`/`hx`/`helix`, editing a file | The file name | The title nvim sets (`<file> \| <org/repo>`, astrocore `custom_title`), read from `#{pane_title}` by the format itself, so a buffer switch relabels the tab immediately |
+| Anything else, or an editor with no file | Repo the cwd belongs to (walks up for `.git`); the directory name outside a repo; `~` at home | `tab-label.sh`, run as an async `#()` job. When its output differs from the current name, it re-arms `automatic-rename` so tmux relabels right after a `cd` instead of on the next keystroke |
+
+Labels longer than 27 characters end in `…`. The icon comes from tmux-nerd-font-window-name.
+
+## Plugins
+
+| Plugin | Settings |
+| --- | --- |
+| `tmux-plugins/tpm` | Plugin manager |
+| `tmux-plugins/tmux-sensible` | Defaults |
+| `joshmedeski/tmux-nerd-font-window-name` | Fills `#{window_icon}` from `tmux-nerd-font-window-name.yml` |
+| `tmux-plugins/tmux-resurrect` | `@resurrect-capture-pane-contents on` |
+| `tmux-plugins/tmux-continuum` | `@continuum-save-interval 10`, `@continuum-restore on` |
+| `prdlk/tmux-palette-plugin` | Fork of [eduwass/tmux-palette](https://github.com/eduwass/tmux-palette) that adds a custom palette `query` item (an item for the typed text, listed after the matches). `@palette-key C-Space` (root table, no prefix). Needs [Bun](https://bun.sh); tpm runs `bun install` on first load |
+
+### Command palette
+
+`ctrl+space` opens tmux-palette, a fuzzy command list in a popup. Its user config lives in `~/.config/tmux-palette/` (the [prdlk/tmux-palette](https://github.com/prdlk/tmux-palette) external):
+
+| File | Contents |
+| --- | --- |
+| `commands.json` | The kitty launchers ported as palette items: **Lazygit** (90% popup in the pane's cwd; kitty `ctrl+shift+g`), **Yazi** (new window; kitty `ctrl+shift+f`), **Neovim Split** (nvim in a split to the left, 60% of the pane; alias `nv`; kitty `ctrl+shift+e`), **Shell History (atuin)** (`atuin-pick` in a 25% split below; kitty `ctrl+shift+p`). Also **btop** (80% popup; aliases `top`, `htop`), **Lazydocker** (90% popup in the pane's cwd; alias `dd`), **mandible** (80% popup running [`mandible-pick`](../shell/scripts.md#mandible-pick); alias `man`), **television** (`tv channels`, the [channel picker](../tools/television.md), in a new window in the pane's cwd; alias `tv`), **gitframe** (git diff viewer in a new window in the pane's cwd; alias `gf`), **omp** (opens the omp palette; aliases `agent`, `ai`), **Project Tasks** (opens the tasks palette), **Sessions** (opens the sessions palette; aliases `sx`, `ss`), **Save Sessions**, and **Restore Sessions** (resurrect). Programs are started with `exec`, so the tab icon is the program's, not the shell's |
+| `palettes/tasks.json` | The **Project Tasks** palette (`prefix t`, Ghostty `ctrl+shift+p` / `ctrl+shift+space`), fed by [`pj-palette`](../shell/scripts.md#pj-palette): running background tasks under Running, then `bun install`, `bun run dev`, `uv sync`, `uv run python`, `make`, `go run .`, `cargo run`, `docker compose up` as Quick items when the project has them, then every task `pj` finds, grouped by tool. One-off tasks run in a full-width split along the bottom (25% of the window) in their directory; `ctrl-c` stops a running task, and once it has exited, `enter` or `ctrl-c` closes the pane. Dev servers (`dev`/`start`/`serve`/`watch`/`preview` tasks) and `docker compose up` run in a background session `<session>:<tool-and-command>` shown in a popup: `q` hides it with the task still running, `ctrl-c` asks `Stop <session>? (y/n)` and on `y` stops the task and closes it |
+| `palettes/omp.json` | The **omp** palette, fed by [`pj-palette --omp`](../shell/scripts.md#pj-palette): this tmux session's `<session>:omp` (open it, or start it when not running), every other tmux session's running omp, and a Quit item per session. Running agents have a green icon and show `open` or `hidden` |
+| `palettes/sessions.json` | The **Sessions** palette (`prefix o`, Ghostty `ctrl+shift+o`), fed by [`tmux-sessions`](../shell/scripts.md#tmux-sessions): Sessions (the last one first, attached ones green), Windows, Zoxide, Config, Rename, Kill. Its `query` item lists the typed text last; `enter` on it runs `tmux-sessions --new <text>` |
+| `hidden.json` | Hides the built-in **Switch Theme...** item, and with it the Appearance section: the palette stays on the fixed CherryBlossom `theme.json` |
+| `shortcuts.json` | Ghostty `ctrl+shift` chords shown next to the built-in items they trigger (New Window → `Ctrl+Shift+T`, …) |
+| `theme.json` | CherryBlossom: bg `#222120`, panel `#2e2c2b`, selected `#453130` (the active-tab plate), muted `#a6958f`, accent `#cf716f` |
+
+### Persistence
+
+resurrect saves sessions, windows, panes, cwds, pane contents, and a default set of programs (nvim, less, man, …). Keys: `prefix C-s` saves, `prefix C-r` restores. continuum saves automatically every 10 minutes. When a tmux server starts and no other tmux server is running, continuum restores the last save. In practice that means the first Ghostty window after login or a reboot.
+
+## tmux-nerd-font-window-name.yml
+
+`show-name: false`, because `automatic-rename-format` supplies the label. The icon sits on the left, with a fallback icon and a blank multi-pane icon. Icons are defined for `mprocs`, `mm`, `macmon`, `make`, `zsh`, `nvim`, `devbox`, `psql`, `yazi`, `lazygit`, `gh`, `tv`, `docker`, `bun`, `node`, `npm`, `pnpm`, `go`, `bunx`, `claude`, `omp`, and `gitframe`. The plugin parses the YAML with awk and does not interpret `\U` escapes, so the glyphs are literal characters.
+