Friday Night Wiki
TopicsTagsAbout
Buy me a coffee
tmux Tutorial

Status Line: The Bar at the Bottom, Made Useful

Anatomy

The status line has three areas:

  • Left: by default, the session name in brackets
  • Middle: the list of windows in the current session
  • Right: by default, the hostname and time

The default looks something like:

[work] 0:editor- 1:shell* 2:logs           "hostname" 14:32 20-Apr-26

* marks the current window. - marks the most-recently-visited other window.

Each piece is configurable. Most tmux dotfiles you see online are 30% colour scheme tweaks to this line.

Core Options

set -g status on                      show the status line at all
set -g status-interval 5              refresh every 5 seconds
set -g status-position bottom         top or bottom
set -g status-justify left            left, centre, or right for the window list

And the three regions:

set -g status-left   "..."
set -g status-right  "..."
setw -g window-status-current-format "..."
setw -g window-status-format "..."

Walk through each.

Format Strings

Status line content is a string with embedded format specifiers, which look like #{name} or #[style]. tmux substitutes them at refresh time.

Common variables:

#S        session name
#W        window name
#I        window index
#F        window flags (*, -, Z, etc.)
#P        pane index
#T        pane title
#H        hostname (full)
#h        hostname (short)
#D        pane ID (internal)

Formatted differently:

#{session_name}        same as #S
#{window_index}        same as #I
#{pane_current_path}   the cwd of the focused pane's process
#{pane_current_command}  the running command
#{client_prefix}       1 if prefix is being held, else 0

Time:

#{T:%H:%M}             format the current time with strftime
#(date +%H:%M)         run a shell command and embed the output

#() runs a shell command every status-interval seconds. Don't run anything slow.

Styling

Wrap a run of text in style specifiers:

#[fg=colour208,bg=colour234,bold]  session: #S  #[default]

Styles:

fg=colour208        foreground (256-colour palette)
bg=default          background
fg=#ff8800          24-bit colour hex
bold                bold
dim                 dim
italics             italics
underscore          underline
reverse             swap fg and bg
blink               blink (if the terminal cooperates)
nobold  noitalics   turn off
#[default]          reset to the default style

Pick colours from the 256-colour palette. Useful ones:

  • colour208 is a warm orange
  • colour16 is black, colour15 is bright white
  • colour234 is a very dark grey (good status background)
  • colour244 is a medium grey

A table is in :help terminal-colours in tmux (or online).

Left: Session Indicator

A clean, minimal left side:

set -g status-left-length 30
set -g status-left "#[fg=colour208,bold] #S #[default] "

Shows the session name in orange bold, with padding. Cap the total length so long names don't push the window list off.

Or add the prefix indicator, showing when you've pressed prefix:

set -g status-left "#[fg=colour208,bold] #S #[fg=colour161]#{?client_prefix,PREFIX,} "

That #{?...} is a conditional: "if client_prefix is truthy, print PREFIX, else nothing". Handy visual cue.

Right: Clock and Host

set -g status-right-length 60
set -g status-right "#[fg=colour244] #h | %H:%M | %d %b "

Shows hostname, time, and date.

Shell commands on the right

Battery, load average, or git branch:

set -g status-right "#[fg=colour244] #(uptime | cut -d, -f3-) | %H:%M "

Runs uptime every status-interval seconds. Keep output short; the status line isn't much room.

For git branch (if the current pane is in a repo):

set -g status-right "#(cd #{pane_current_path} && git rev-parse --abbrev-ref HEAD 2>/dev/null) | %H:%M"

Window List Formats

window-status-format formats every window in the list except the active one. window-status-current-format formats the active window.

Defaults look like:

setw -g window-status-format         "#I:#W#F"
setw -g window-status-current-format "#I:#W#F"

A styled version with clearer separation:

setw -g window-status-format \
  "#[fg=colour244] #I #W#F "
setw -g window-status-current-format \
  "#[fg=colour16,bg=colour208,bold] #I #W#F "

Now the current window is a bold highlighted block; the rest are subtle grey. Easy to find focus at a glance.

Separators

Minimal separator:

setw -g window-status-separator " "

A Full Example

Pulling it together:

# status
set -g status on
set -g status-interval 5
set -g status-position bottom
set -g status-justify left
set -g status-style fg=colour250,bg=colour234

set -g status-left-length 40
set -g status-right-length 60

set -g status-left "#[fg=colour208,bold] #S #[fg=colour161]#{?client_prefix,• ,}"
set -g status-right "#[fg=colour244] #h #[fg=colour250] %H:%M #[fg=colour244] %d %b "

setw -g window-status-format         "#[fg=colour244] #I  #W "
setw -g window-status-current-format "#[fg=colour16,bg=colour208,bold] #I  #W "
setw -g window-status-separator ""

Reload. The result is a clean, readable status line with the session highlighted, the current window in orange, prefix indicator when active, and time plus hostname on the right.

Beyond the Status Line: Message and Mode Styles

tmux styles messages and mode indicators with separate options:

set -g message-style "fg=colour16,bg=colour208,bold"
set -g mode-style "fg=colour16,bg=colour208,bold"

Message style applies to the transient lines at the bottom (:display-message output). Mode style applies to selections in copy mode. Match them to your status line for visual consistency.

When to Stop Customising

Status-line tinkering is one of tmux's great time sinks. A good rule: spend an hour on it once, pick something you like, then stop. Every hour past that is not making you faster at work.

Reasonable defaults:

  • Session name on the left
  • Window list in the middle
  • Time + one useful thing (host, branch, load) on the right
  • One colour for current window, subtle grey for others
  • No ASCII art; no emojis; no animations

If you find yourself shopping for plugins that add animated status bars, close them all and breathe.

Hiding the Status Line

set -g status off

Or toggle at runtime:

<prefix> :set status

Some people hide the status line during presentations or when they want every pixel for their editor. Bind a toggle:

bind S set -g status

Common Pitfalls

"Format strings like #S show literally instead of substituting." You're using single quotes where double quotes are needed, or missing a " somewhere. Paste carefully.

"My shell command in the status line is slow." #(...) runs every status-interval. Set interval higher (set -g status-interval 15) or cache the output.

"Colours look wrong after a reload." tmux caches some colour info per session. <prefix> :refresh-client forces a redraw.

"The prefix indicator stays on." #{?client_prefix,...,} only evaluates on status refresh. With status-interval 5, the indicator can lag. Lower the interval to 1 if you want it snappy.

"Right side is cut off." Increase status-right-length. Also check that your total left + windows + right fits the terminal width.

Next Steps

Continue to 09-scripting.md to drive tmux from shell scripts.