From 9e227b416d742367a22cc0c5ace15042f93af1ca Mon Sep 17 00:00:00 2001 From: Prad Nukala Date: Thu, 8 Oct 2026 11:29:11 -0400 Subject: [PATCH] docs(docs): expand terminal and tmux documentation with launch commands, prompts, persistence, and keybinding updates --- docs/desktop/hyprland.mdx | 2 +- docs/desktop/niri.mdx | 2 +- docs/shell/bash-zsh.mdx | 3 +- docs/shell/index.mdx | 2 +- docs/shell/starship.mdx | 4 +- docs/terminal/ghostty.mdx | 62 ++++++++++++++----------- docs/terminal/herdr.mdx | 2 +- docs/terminal/index.mdx | 6 +-- docs/terminal/kitty.mdx | 2 +- docs/terminal/tmux.mdx | 97 +++++++++++++++++++++++---------------- 10 files changed, 106 insertions(+), 76 deletions(-) diff --git a/docs/desktop/hyprland.mdx b/docs/desktop/hyprland.mdx index 2cc8c99..7b92b9d 100644 --- a/docs/desktop/hyprland.mdx +++ b/docs/desktop/hyprland.mdx @@ -279,7 +279,7 @@ Focuses an app's window, cycles to the next one on repeated presses, or launches | `ghostty` | `ghostty` | `ghostty` | | `browser` | zen, brave, chromium, google-chrome, firefox, librewolf, vivaldi, microsoft-edge, helium — excluding `chrome-`/`webapp-` web apps | `omarchy-launch-browser` | | `brave` | `^brave` (Brave Origin and its web apps) | `brave-origin` | -| `terminal` | kitty, alacritty, ghostty, foot, wezterm (Tern, the scratchpad terminal, does not match) | `omarchy-launch-terminal` | +| `terminal` | kitty, alacritty, ghostty, foot, wezterm (Tern, the scratchpad terminal, does not match) | `omarchy-launch-terminal` (`xdg-terminal-exec`: the OS default terminal from `~/.config/xdg-terminals.list`, in the focused terminal's cwd) | | `ai` | `claude\|hermes` | `hermes desktop` | | anything else | `^APP$` | the argument as a command | diff --git a/docs/desktop/niri.mdx b/docs/desktop/niri.mdx index 8fa471c..34504f8 100644 --- a/docs/desktop/niri.mdx +++ b/docs/desktop/niri.mdx @@ -433,7 +433,7 @@ Deployed to `~/.config/niri/scripts/`. `70-binds.kdl` binds none of them, so the | `kitty-CLASS` | exactly that class | `kitty --class kitty-CLASS` (optional command from the empty `KITTY_CMDS` map) | | `ghostty` | `ghostty` | nothing, prints a message | | `browser` | `^(zen\|brave\|chromium\|firefox)` | `zen` | -| `terminal` | `kitty\|alacritty\|ghostty` | `kitty` | +| `terminal` | `kitty\|alacritty\|ghostty` | `xdg-terminal-exec` (the OS default terminal from `~/.config/xdg-terminals.list`) | | `ai` | `claude\|hermes` | `hermes desktop` | | anything else | exact app-id | the argument as a command | diff --git a/docs/shell/bash-zsh.mdx b/docs/shell/bash-zsh.mdx index 2b55b1f..95357f7 100644 --- a/docs/shell/bash-zsh.mdx +++ b/docs/shell/bash-zsh.mdx @@ -46,7 +46,8 @@ Interactive shells only (`[[ $- != *i* ]] && return`). In order: 6. Sources `~/.config/zsh/keybinds.zsh`. 7. `eval "$(suv init zsh)"` if suvadu is installed. 8. Sources `~/.config/envman/load.sh` if it is non-empty. -9. `eval "$(starship init zsh)"` if starship is installed. +9. **Prompt.** If starship is installed: `eval "$(starship init zsh)"`, `ZLE_RPROMPT_INDENT=0` (the right-prompt clock sits flush with the edge), and a transient prompt. A `line-finish` zle hook swaps `PROMPT`/`RPROMPT` to the `transient` and `transient_right` starship profiles (`❯`, colored by the last exit status, and the time) and redraws, so past prompts collapse as in fish; a `precmd` hook restores the full prompt. Starship's zsh init also sets `PROMPT2`, the `∙` continuation prompt for unfinished lines. See [Starship](/shell/starship#shell-integration). + **Window title.** A `precmd` hook ports `fish_title`: it sets the terminal title to `%~`, prefixed with the first 10 characters of the hostname over SSH, and inside tmux also sets the window name (`ESC k`), like fish's `50-terminal-title.fish`. Unlike fish's `prompt_pwd`, the path is not abbreviated. 10. `eval "$(tv init zsh)"` if `tv` is installed (ctrl-t smart autocomplete). 11. **Syntax highlighting.** Sources the first `zsh-syntax-highlighting.zsh` found in `/usr/share/zsh/plugins/zsh-syntax-highlighting/`, `/opt/homebrew/share/zsh-syntax-highlighting/`, or `/usr/local/share/zsh-syntax-highlighting/`. The comment says this must stay last, because it wraps every zle widget defined before it. 12. **atuin.** `eval "$(atuin init zsh)"` if atuin is installed. This line comes after the syntax-highlighting block, so despite the comment, syntax highlighting is not actually last. atuin loads after tv, so it keeps ctrl-r. diff --git a/docs/shell/index.mdx b/docs/shell/index.mdx index bbdc17e..8b3d33b 100644 --- a/docs/shell/index.mdx +++ b/docs/shell/index.mdx @@ -21,7 +21,7 @@ fish is the main interactive shell. bash and zsh are set up to feel the same: th | Concern | fish | bash | zsh | | --- | --- | --- | --- | | Aliases | `conf.d/20-aliases.fish` (hand-maintained) | `~/.config/shell/aliases.sh` (rendered from YAML) | same as bash | -| Prompt | starship + transient prompt | starship | starship | +| Prompt | starship + transient prompt | starship | starship + transient prompt | | History | atuin (hishtory also sourced if installed) | atuin | atuin, plus suvadu if installed | | Key bindings | vi mode plus custom binds | atuin defaults only | emacs keymap plus ports of the fish binds | | cd-style helpers | `functions/*.fish` | `~/.config/bash/functions/*.bash` | `~/.config/zsh/functions/*.zsh` | diff --git a/docs/shell/starship.mdx b/docs/shell/starship.mdx index dd7f244..8e8a7bc 100644 --- a/docs/shell/starship.mdx +++ b/docs/shell/starship.mdx @@ -17,10 +17,12 @@ The file is not a template and applies on every role. `starship` is in `.chezmoi | --- | --- | | fish | `conf.d/40-tools.fish` runs `starship init fish`, then `config.fish` runs it again and calls `enable_transience` | | bash | `eval "$(starship init bash)"` in `~/.bashrc` | -| zsh | `eval "$(starship init zsh)"` in `~/.zshrc` | +| zsh | `eval "$(starship init zsh)"` in `~/.zshrc`, plus a transient-prompt hook | With transience in fish, past prompts in the scrollback collapse to the output of `starship_transient_prompt_func` (`starship module character`, the `❯` alone) and `starship_transient_rprompt_func` (`starship module time`). See [fish](/shell/fish#configfish). +zsh has no built-in transience, so `~/.zshrc` collapses past prompts itself, rendering the `transient` (`$character`) and `transient_right` (`$time`) entries under `[profiles]` with `starship prompt --profile`. It uses profiles rather than `starship module` because only `starship prompt` wraps color escapes in zsh's `%{…%}`; without them zsh miscounts the right prompt's width. zsh also gets starship's default `∙` continuation prompt (`PROMPT2`). See [bash and zsh](/shell/bash-zsh#zshrc). + ## Layout ```toml ~/.config/starship.toml diff --git a/docs/terminal/ghostty.mdx b/docs/terminal/ghostty.mdx index df72d48..a00a4c2 100644 --- a/docs/terminal/ghostty.mdx +++ b/docs/terminal/ghostty.mdx @@ -1,9 +1,9 @@ --- title: Ghostty -description: Ghostty configuration and its herdr key sync. +description: Ghostty as a tmux-only terminal — every window attaches to tmux, and ctrl+shift chords drive tmux. --- -GPU terminal emulator kept alongside kitty. Its bindings send the same herdr prefix bytes as the kitty herdr host. +Ghostty is only a [tmux](/terminal/tmux) client. tmux owns tabs (windows), splits (panes), sessions, and persistence. Ghostty draws the text and handles the clipboard and font size. | | | | --- | --- | @@ -17,47 +17,57 @@ Ghostty reads both `config` and `config.ghostty`. `config` holds all settings; ` | Option | Value | | --- | --- | -| `font-family` / `font-size` | `Victor Mono NF` / `13` | +| `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` (bezelless: text runs to the window edge) | +| `window-padding-x/y` | `2` | | `cursor-style` | `underline`, blinking | -| `scrollback-limit` | `3023` | +| `scrollback-limit` | `3023` (tmux keeps the real scrollback: `history-limit 50000`) | | `mouse-hide-while-typing` | `true` | | `copy-on-select` | `false` | | `confirm-close-surface` | `false` | | `app-notifications` | `no-clipboard-copy,no-config-reload` | | `quit-after-last-window-closed` | `false`, delay `5m` | -| `command` | `tmux new-session -A -s main` (every window and tab attaches to tmux session `main`, creating it when missing) | +| `command` | `tmux new-session -A -s main`: every window attaches to tmux session `main` and creates it if it is missing | | `shell-integration` | `detect`, features `cursor,sudo,title,no-cursor` | | `gtk-single-instance` | `true` | +## Persistence + +Closing Ghostty only detaches from tmux; the shells keep running in the tmux server. Across reboots, tmux-continuum saves the layout every 10 minutes. When the first Ghostty window starts a new tmux server, continuum restores the last save. See [tmux](/terminal/tmux#persistence). + ## Keybindings -| Key | Action | +`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. Each `ctrl+shift` chord sends tmux's second prefix, `ctrl+b` (`\x02`), followed by a key. + +| Key | Ghostty action | | --- | --- | -| `cmd+c` / `cmd+v` | Copy / paste | -| `cmd+n` | New window | +| `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 a literal newline | -| `ctrl+shift+alt+,` | Reload config | -### herdr sync - -Placed last so they override defaults. Each sends `ctrl+b` (`\x02`) followed by a key; see [herdr](/terminal/herdr). - -| Key | Sends | -| --- | --- | -| `ctrl+shift+n` | `prefix %` (split vertical) | -| `ctrl+shift+t` | `prefix c` | -| `ctrl+tab` / `ctrl+shift+tab` | `prefix n` / `prefix p` | -| `ctrl+shift+f` | `prefix s` (workspace picker) | -| `ctrl+shift+l` / `ctrl+shift+h` | `prefix .` / `prefix ,` (next / previous agent) | -| `ctrl+shift+j` / `ctrl+shift+k` | `prefix j` / `prefix k` (next / previous workspace) | -| `super+enter` | `prefix N` | -| `super+r` | `prefix W` | -| `ctrl+shift+r` | `prefix T` | -| `ctrl+shift+,` | `prefix S` (herdr settings) | +| Key | Sends | tmux action | +| --- | --- | --- | +| `ctrl+shift+t` | `prefix c` | New window (tab) in 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+e` / `ctrl+shift+j` | `prefix h` | Split below | +| `ctrl+shift+o` | `prefix o` | Session picker (tmux-sessionx) | +| `ctrl+shift+x` | `prefix x` | Kill pane | +| `ctrl+shift+enter` / `ctrl+shift+z` | `prefix z` | Zoom pane | +| `ctrl+shift+f` | `prefix /` | Search scrollback upward | +| `ctrl+shift+page_up` | `prefix [` | Copy mode | +| `ctrl+shift+p` | `prefix :` | Command prompt | +| `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 diff --git a/docs/terminal/herdr.mdx b/docs/terminal/herdr.mdx index 8e5cc5c..0615c46 100644 --- a/docs/terminal/herdr.mdx +++ b/docs/terminal/herdr.mdx @@ -10,7 +10,7 @@ herdr is a terminal multiplexer with workspaces, tabs and panes, a sidebar, a pr | Source | `dot_config/herdr/config.toml`, `dot_config/herdr/plugins.json`, `dot_config/herdr/plugins/config/`, `dot_config/herdr/empty_dot_plugins.lock`, `dot_config/herdr/kitty.conf`, `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](/terminal/kitty)); Ghostty keys send the same prefix bytes | +| Launch | kitty `super+a` (see [kitty](/terminal/kitty)) | ## config.toml diff --git a/docs/terminal/index.mdx b/docs/terminal/index.mdx index ee5d52f..0b0c928 100644 --- a/docs/terminal/index.mdx +++ b/docs/terminal/index.mdx @@ -5,13 +5,13 @@ sidebar: label: Overview --- -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 kept as a secondary terminal whose bindings drive herdr the same way. +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](/terminal/kitty) | `dot_config/kitty/` | Main config, host configs (tmux, herdr, goliath), kittens, custom tab bar | -| [Ghostty](/terminal/ghostty) | `dot_config/ghostty/` | Config, herdr key sync, themes | -| [tmux](/terminal/tmux) | `dot_config/tmux/` | Prefix, bindings, tpm plugins, dotbar status line, Niri titles | +| [Ghostty](/terminal/ghostty) | `dot_config/ghostty/` | tmux-only terminal: ctrl+shift chords → tmux, themes | +| [tmux](/terminal/tmux) | `dot_config/tmux/` | Prefix, bindings, kitty-style tabs with Nerd Font icons, resurrect/continuum persistence, Niri titles | | [herdr](/terminal/herdr) | `dot_config/herdr/`, `dot_config/herdr-nvim/` | Agent-aware multiplexer: keys, theme, plugins, Claude hook | ## Shared conventions diff --git a/docs/terminal/kitty.mdx b/docs/terminal/kitty.mdx index db9b564..c9b37e7 100644 --- a/docs/terminal/kitty.mdx +++ b/docs/terminal/kitty.mdx @@ -160,7 +160,7 @@ Launched by `super+t`. kitty stays a dumb terminal; tmux owns panes, windows and ### 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`. Keys mirror the [Ghostty](/terminal/ghostty) config so both drive herdr identically; an uppercase letter after `\x02` is the shift variant. See [herdr](/terminal/herdr). +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](/terminal/herdr). | Key | Sends / does | | --- | --- | diff --git a/docs/terminal/tmux.mdx b/docs/terminal/tmux.mdx index c18a9a3..349a6f1 100644 --- a/docs/terminal/tmux.mdx +++ b/docs/terminal/tmux.mdx @@ -1,62 +1,75 @@ --- title: tmux -description: tmux prefix, options, bindings, tpm plugins and the dotbar status line. +description: tmux prefix, bindings, kitty-style window tabs with Nerd Font icons, and resurrect/continuum persistence. --- -Terminal multiplexer. Used locally through the kitty tmux host (`super+t` in [kitty](/terminal/kitty)) and remotely on goliath. +Terminal multiplexer. [Ghostty](/terminal/ghostty) 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 | `dot_config/tmux/tmux.conf`, `dot_config/tmux/tmux-nerd-font-window-name.yml`, `dot_config/tmux/executable_niri-title.sh` | -| Target | `~/.config/tmux/` | +| Source | `dot_config/tmux/tmux.conf`, `dot_config/tmux/tmux-nerd-font-window-name.yml`, `dot_config/tmux/executable_tab-label.sh`, `dot_config/tmux/executable_niri-title.sh`, `dot_config/omarchy/themed/tmux.conf.tpl`, `dot_config/omarchy/hooks/theme-set.d/executable_tmux-tabs` | +| Target | `~/.config/tmux/`, `~/.config/omarchy/` | | Install | `tmux` in `.chezmoidata/packages.yaml` (pacman, brew) | -tpm is a `git-repo` external in `.chezmoiexternal.toml`, cloned to `~/.config/tmux/plugins/tpm` when missing. `tmux.conf` ends with `run '~/.config/tmux/plugins/tpm/tpm'`. Plugins tpm installs (`prefix I`) land next to it and are ignored by chezmoi. [Ghostty](/terminal/ghostty) starts every surface in `tmux new-session -A -s main`. +tpm is a `git-repo` external in `.chezmoiexternal.toml`, cloned to `~/.config/tmux/plugins/tpm` when missing. `tmux.conf` ends with `run '~/.config/tmux/plugins/tpm/tpm'`. Plugins installed by tpm (`prefix I`) land next to it and are ignored by chezmoi. ## Options -The prefix is the default `ctrl+b`. +The prefix is `ctrl+space`; `ctrl+b` is `prefix2` (the byte Ghostty sends). | Option | Value | | --- | --- | -| `default-terminal` | `tmux-256color`; `xterm-kitty:Tc` override; features `RGB:usstyle:hyperlinks:clipboard:extkeys` | -| `extended-keys` | `always`, format `csi-u` | +| `default-terminal` | `tmux-256color`; `RGB` override for every terminal; `clipboard` feature; `extkeys` for xterm-kitty | +| `extended-keys` | `on`, format `csi-u` | | `base-index` / `pane-base-index` | `1` / `1`; `renumber-windows on` | -| `status-position` | `top` | -| `allow-passthrough` | `on` (kitty graphics for yazi previews); `TERM`, `TERM_PROGRAM` added to `update-environment` | -| `set-clipboard` | `on` (OSC 52) | -| `mouse` | `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`, `set-titles-string "#T (#S)"`, `status-interval 1`, `automatic-rename on` | +| `set-titles` | `on`, `#h:#W` | +| `automatic-rename-format` | `#{window_icon}