tmux/Pane/Border

• Pane border

  • In tmux, pane borders are the lines that separate the tmux/Panes in a window. Border options control their characters, appearance, active-pane indicators, and optional status text.
  • The options below are window options. Use set-option -g to set the inherited global value or set-option -w to set the value for one window.

  • Options

    • tmux/Option/pane-active-border-style

      • pane-active-border-style

        • Sets the foreground and background style of the tmux/Pane/Active border. Text attributes such as bold are ignored.
        • Example: tmux set-option -g pane-active-border-style fg=colour46
    • tmux/Option/pane-border-format

      • pane-border-format

        • Sets the format text shown in pane-border status lines. It accepts tmux formats such as #{pane_index}, #{pane_title}, and #{pane_active}.
        • The text appears when tmux/Option/pane-border-status is set to a visible position.
        • Example: tmux set-option -g pane-border-format ' #{pane_index}: #{pane_title} '

        • The stock value already renders the pane title

          • The manual states no default for this option, so the value has to be read off a server started with no config on the build in use rather than looked up. On tmux/v/3.7b, measured 2026/08/24:
            • sh

              tmux -L stock -f /dev/null new-session -d
              tmux -L stock show-options -gv pane-border-format
              # #{?pane_active,#[reverse],}#{pane_index}#[default] "#{pane_title}"#{?#{mouse},…}
              tmux -L stock kill-server

          • The "#{pane_title}" in there is why naming panes with select-pane -T needs no format of its own: turning tmux/Option/pane-border-status on is the whole of it. This is the reason My/Dotfiles change track-tmux-pane-border-status is one line — the running server's value was identical to stock, character for character, so tracking it would have been upkeep that changed no behavior.
          • Read what a given pane's border line will say, with the format expanded in that pane's context:
            • sh

              tmux display-message -p -t '<session>:<window>.1' '#{E:pane-border-format}'

    • tmux/Option/pane-border-indicators

      • pane-border-indicators

        • Controls the visual markers used to identify the tmux/Pane/Active.

        • Values

          • off — show neither indicator.
          • colour — color half of the shared border when a window contains exactly two panes.
          • arrows — draw arrows pointing toward the active pane.
          • both — use the color and arrow indicators together.
    • tmux/Option/pane-border-lines

      • pane-border-lines

        • Selects the characters used to draw pane borders.

        • Values

          • single — single ACS or UTF-8 lines.
          • double — double UTF-8 lines.
          • heavy — heavy UTF-8 lines.
          • simple — ASCII lines.
          • number — pane numbers.
          • spaces — space characters.
          • none — no border for floating panes.
        • double and heavy fall back to ACS line drawing when UTF-8 is unavailable.
    • tmux/Option/pane-border-status

      • pane-border-status

        • A tmux window option that controls whether pane-border status lines are shown and where they appear. The default is off.

        • My Notes

          • This is part of My/Pref/Dev/Tool/tmux/Basic Prefs
        • It is the option a pane title depends on. Titles are set with select-pane -T and stored on the pane whatever this option says, but a border status line is the only place tmux draws them — so at the default off the titles are all still set and none of them can be read. Nothing errors and no value is unset, so nothing reports it.
        • Each pane gives up one row of its height to the line. Measured 2026/08/24 on tmux/v/3.7b with a 50-row client: two side-by-side panes are 49 rows tall at top and 50 rows tall at off.

        • Values

          • off — hide pane-border status lines. The default.
          • top — show a status line along the top border of each pane.
          • bottom — show a status line along the bottom border of each pane.
          • top-floating — show a top status line only on floating panes.
          • bottom-floating — show a bottom status line only on floating panes.

        • Usage

          • Set it in tmux/Config:
            • sh

              set -g pane-border-status top

          • set -g and setw -g are equivalent here, despite this being a window option: tmux resolves an option's scope from its name rather than from the flag. Measured 2026/08/24 on tmux/v/3.7b, a config containing either spelling leaves the option reporting top under both show-options -gv and show-options -gwv.
          • Or at runtime with tmux/Command/set-option/g:
            • sh

                tmux set-option -g pane-border-status top

          • Set it for the current window only:
            • sh

              tmux set-option -w pane-border-status top

          • Read the current value with tmux/Command/show-options/gv:
            • sh

              tmux show-options -gv pane-border-status

          • Turn it off globally:
            • sh

              tmux set-option -g pane-border-status off

        • Displayed text

          • tmux/Option/pane-border-format controls the text in the border status line, and its stock value already renders "#{pane_title}" — so turning this option on is enough to make a title readable, with no format to write.
          • Render what a pane's border line will say, without attaching a client:
            • sh

              tmux display-message -p -t '<session>:<window>.1' '#{E:pane-border-format}'
              # #[reverse]1#[default] "Seneschal HUD"

        • Set to top here, in the config

          • Every managing seat in My/AI/Agent/Fleet keeps a titled viewer pane beside its chat pane, so the window tree names both the repository the agent works in and what each pane is for. That whole convention rests on this option: at off the names are set and invisible.
          • top rather than bottom puts each name above the content it names, the way a title bar does. bottom would put it below, and for the lowest pane in a window it would sit directly against the client's own tmux/Status Line, stacking two unrelated bars of text. Both spend one row per pane, so nothing is saved by the swap.
          • It began as a runtime set -g, which is server-global and outlives every session on that server but not the server: on the next tmux kill-server, or the first session after a reboot, it would have returned to off and every pane title in the fleet would have stopped being readable.
          • It is now in the config file. 2026/08/24, set -g pane-border-status top was added to the chezmoi source for ~/.config/tmux/tmux.conf with a comment giving the reason — My/Dotfiles change track-tmux-pane-border-status, the companion to track-tmux-status-left-length found the same morning.
            • sh

              tmux -L pbstest -f ~/.config/tmux/tmux.conf new-session -d -s hayward-2026-08-24
              tmux -L pbstest split-window -h -t hayward-2026-08-24
              tmux -L pbstest select-pane -t 'hayward-2026-08-24:0.1' -T 'Seneschal HUD'
              tmux -L pbstest show-options -gv pane-border-status              # top
              tmux -L pbstest display-message -p -t 'hayward-2026-08-24:0.1' '#{E:pane-border-format}'
              # #[reverse]1#[default] "Seneschal HUD"
              tmux -L pbstest kill-server

            • An isolated socket is the way to check this while a fleet is attached — kill-server on the default socket would take every seat's session down with it.
          • The negative control is the instructive half. On a server started with -f /dev/null, the same select-pane -T call succeeds, list-panes still reports 1=Seneschal HUD, and there is simply no border status line in which to read it. Attaching a client to each in turn and capturing the top row shows it plainly: the configured server draws ──0 "Seneschal chat"───┬──1 "Seneschal HUD"───, and the unconfigured one draws nothing there at all — the shell content starts on row one.

        • The neighbouring border options are not in the config

          • Measured 2026/08/24 on tmux/v/3.7b against a -f /dev/null server, tmux/Option/pane-border-format and tmux/Option/pane-border-style on the running server are identical to stock, while three depart from it: tmux/Option/pane-border-indicators is both against a stock colour, tmux/Option/pane-border-lines is double against a stock single, and tmux/Option/pane-active-border-style is fg=colour46,bold against a stock expression that colours by pane mode.
          • Those three are residue of the retired oh-my-tmux layer — set -g pane-border-indicators both appears verbatim in its tmux.conf.local in the dotfiles' history — and they are deliberately not tracked. They are about how the border looks rather than whether it carries a name, so letting them fall back to stock on the next server start is the intended outcome.

        • Related

          • tmux/Keyshort/Pane/Show Pane Titles
    • tmux/Option/pane-border-style

      • pane-border-style

        • Sets the foreground and background style of borders around panes other than the tmux/Pane/Active. Text attributes are ignored.
        • Example: tmux set-option -g pane-border-style fg=colour238

  • Example configuration

    • sh

      set-option -g pane-border-lines heavy
      set-option -g pane-border-style fg=colour238
      set-option -g pane-active-border-style fg=colour46
      set-option -g pane-border-indicators arrows
      set-option -g pane-border-status top
      set-option -g pane-border-format ' #{pane_index}: #{pane_title} '

  • Related

    • tmux/Pane/Q/How can I display the names of the panes in tmux?
    • tmux/Q/How can I put a thick border around the focused pane?