How to customize the tmux status bar

Customizing the tmux status bar changes what appears at the edge of each client so the active session, current window, and clock are easier to read at a glance. It is the normal way to move the bar to the top, simplify the default right side, or make the active window stand out more clearly.

Current tmux controls the status line with options such as status-position, status-style, status-left, status-right, and window-status-current-format. By default the bar sits at the bottom, shows the session name on the left, keeps the window list in the middle, and shows pane title plus time and date on the right.

The usual workflow is to edit the tmux config file, reload it into the running server with source-file, and then query the live option values before trusting the visual result alone. Longer left or right segments are clipped by the length limits, so custom hostnames or extra clock text may need matching status-left-length or status-right-length changes.

1. Open the tmux config file used by the running server.

   $ vi ~/.tmux.conf

   Current tmux also reads user config from $XDG_CONFIG_HOME/tmux/tmux.conf or the default ~/.config/tmux/tmux.conf path. Edit that file instead when the running server was started from an XDG config path.

2. Add or update a small status-bar block in the config file.

   set -g status-position top
   set -g status-style 'bg=black,fg=green'
   set -g status-left '#[bold]#S '
   set -g status-left-length 20
   set -g status-right '%H:%M'
   set -g window-status-current-format '#[reverse]#I:#W*#[default]'

   status-style sets the base bar colors. The #[...] sequences are embedded styles inside the left and current-window formats, #S expands to the session name, #I and #W expand to the current window index and name, and %H:%M uses the normal clock format for the right side.

   Increase status-left-length or add status-right-length when longer labels, hostnames, or dates are clipped.

3. Reload the tmux config into the running server.

   $ tmux source-file ~/.tmux.conf

   No output means the file was accepted and the new status-bar settings were applied to the live server.

   Use the XDG config path here as well when that is the file the server is actually using.

   If tmux returns error connecting to /tmp/tmux-UID/default (No such file or directory), there is no running tmux server to reload yet.

   Related: How to reload the tmux config

4. Query the running server to confirm the main status-bar options now match the new block.

   $ tmux show-options -g status-position \; show-options -g status-style \; show-options -g status-left \; show-options -g status-right \; show-options -g window-status-current-format
   status-position top
   status-style bg=black,fg=green
   status-left "#[bold]#S "
   status-right "%H:%M"
   window-status-current-format "#[reverse]#I:#W*#[default]"

   This single tmux command sequence prints the exact option values from the live server instead of relying on the text file alone.

5. Look at any attached tmux client to confirm the visual result.

   The bar should now appear at the top, the session name should render at the left in bold, the active window should stand out in the middle list, and the right side should show only the current time.

   If the middle list still shows generic window names such as bash or zsh, rename the relevant windows so the customized bar is easier to scan.

   Related: How to rename a window in tmux

6. Fix the first invalid line and reload again when tmux reports an option error.

   $ tmux source-file ~/.tmux.conf
   invalid option: status-rght

   tmux keeps the previously loaded status-bar settings until the bad line is corrected and the file is sourced again.