tmux: Per-project status bar

By Przemek, May 2020

I often have multiple tmux sessions running at the same time in separate windows, corresponding to different projects – wouldn’t it be nice to have some visual indication to easily tell one session from the other?

Objective

In this note we describe a setup that automatically bootstraps the tmux session for different projects and configure it so that different colors are used for the status bar, depending on the project.

Prerequisites

I tested this setup on Debian Linux and Mac with tmux 3.0.

Make sure to have the following option in the .tmux.conf file to ensure the 8-bit color palette is handled correctly :

set-option -g default-terminal "screen-256color"

tmux automation using tmuxp

tmuxp is a tool for automating tmux setups. It allows you to describe the desired session state in a YAML file, which can then be loaded to construct the tmux session. For example, a minimal session setup I use when working on this blog looks like so:

session_name: 'blog'
shell_command_before: 
  - cd ~/projects/blog
  - clear
windows:
- window_name: shell
  layout: even-horizontal
  panes:
  - focus: 'true'
  - shell_command: hugo server -D

This file can be then loaded via tmuxp load <path>, resulting in a single window, two-pane tmux session, with hugo server -D running in one of the panes. Before bootstrapping the session, tmuxp will run cd ~/projects/blog, so the tmuxp load command can be issued from any working directory. So far so good!

Setting the colors for the status bar

We can experiment with different status bar colors while in a tmux session:

tmux set status-style bg=colour22,fg=colour255

Here are a few color combinations I like:

[blog] 0:shell- 1:nvim* → bg=colour22,fg=colour255
[blog] 0:shell- 1:nvim* → bg=colour254,fg=colour0
[blog] 0:shell- 1:nvim* → bg=colour3,fg=colour255
[blog] 0:shell- 1:nvim* → bg=colour89,fg=colour255

and we can build more using the color pallette set up by Jonas Jacek – just make sure to refer to colors as colour<number>, I found the Xterm names to usually not work on my machines.

Putting the pieces together

Even though tmuxp supports setting session options via explicit configuration toggles in the YAML file, I ended up just adding a tmux set status-style command in the shell_command_before block:

session_name: 'blog'
shell_command_before: 
  - cd ~/projects/blog
  - tmux set status-style bg=colour22,fg=colour255
  - clear
windows:
- window_name: shell
  layout: even-horizontal
  panes:
  - focus: 'true'
  - shell_command: hugo server -D

This has the advantage of … working as intended. See below for what I think should work but doesn’t, at least with tmux 3.0.

Appendix: what probably should work but doesn’t

Here’s what I think would be the canonical way of setting the session colors via explicit tmuxp option toggles:

session_name: 'blog'
shell_command_before: 
  - 'cd ~/projects/blog'
options:
  status-bg: colour22
  status-fg: colour255
windows:
- window_name: shell
  layout: even-horizontal
  panes:
  - focus: 'true'
  - shell_command: hugo server -D

This seems to yield different results depending on the version of tmux:

on tmux 2.8, I see the config below working reliably and being equivalent to the config above, on both Linux and MacOS
⚠️ on tmux 3.0, I see the config below change the status bar globally for all tmux sessions when a session is loaded, on both Linux and MacOS

I thought this may be due to a backward-incompatible change in tmux that was not handled in tmuxp, but tmux CHANGES between 2.8 and 3.0 don’t seem to note anything relevant, so the mystery persists – in the meantime, using shell_command_before as noted above is a good workaround.