Tmux Redux

In the world of terminal multiplexers, Tmux has been a favorite among developers for almost two decades. Now that we have embraced Agentic Coding (Claude!) tmux has, yet again, become an invaluable tool.

Why Would You Care?

In a typical workflow, you are probably working on multiple projects at the same time (coding agents do not get tired and do not have “gotta do one thing at a time” need). Further, for each of the projects you probably are using multiple terminal tabs:

1. One or more running Claude sessions
2. Several others idling in zsh waiting for you to type something yourself
3. Additional shells running servers, logs, builds non-detached
4. Add to this multiple git worktrees per project

If you just have all these just open as good-old tabs in Terminal.app or iTerm.app, things will quickly get pretty chaotic, with you frantically switching between tabs to find the right one, or color-coding them to the extent that concerns your eye doctor (eye train is a real thing)

Tmux can help!

Disclaimer: there are dedicated, all-in-one solutions such as Cmux and terminal apps like iTerm2 have their own alternatives for tmux. However, if you are already a fan of tmux, or want the flexibility of configuring things to your liking (e.g. what about a beautiful status bar plugin?), then you will forgo the likes of cmus and keep reading this post :)

Irakli’s Setup

Without further ado, let me walk you through my setup, in case you like any of it and want to borrow. Or if you don’t already have it set up, hope it can get you started quickly. You can also point your Claude to this blog post, if you want it to do the job :)

Installation

# on Mac:
> brew install tmux

# on Debian/Ubuntu Linux
> sudo apt install tmux -y

# on Windows? Just kidding! Real programmers don't use Windows! ;)

Installing Plugins

We are going to install a number of plugins:

1. Catppuccin Status Line

A good status line is a critical part of the tmux experience. It allows to quickly see the context (current folder, user, etc.) of each pane as you switch between panes. and catppuccin provides a beautiful and functional status line that integrates well with the overall theme.

Ability to see the current folder of the pane, even if the active app is not a shell, but is a Claude session is VERY helpful. You will be running many Claude sessions and every now and then, trust me, you will forget which folder that particular Claude is running in. Having that information in the status line, easily visible is PRICELESS.

To install:

mkdir -p ~/.config/tmux/plugins/catppuccin
git clone -b v2.3.0 https://github.com/catppuccin/tmux.git ~/.config/tmux/plugins/catppuccin/tmux

‘hint’: make sure to run tmux source ~/.tmux.conf whenever you create or change the tmux config file, to make sure changes take effect!

Additional Essential Plugins:

1. tmux-sensible: provides a set of default configurations that improve the user experience.
2. tmux-resurrect: allows you to save and restore tmux sessions, which is incredibly useful for maintaining your workflow across reboots or when you need to close your terminal.
3. tmux-continuum: provides continuous saving of tmux sessions, complementing tmux-resurrect.
4. tmux-yank: allows you to copy text to the system clipboard easily.

Irakli’s Tmux Config

Before we get to showing the main config file, let’s explain some Tmux terminology, if you are new to tmux.

With Tmux, you can have multiple sessions running. To see list of sessions run tmux ls. Inside a specific session, you will have multiple “panes”. Once you are inside a tmux session, you tell tmux what to do with keyboard shortcuts.

Tmux keyboard shortcuts start with a “prefix”: a key combo that starts action (by default: ctrl-b) followed by another key press that identifies the specific command. For instance, by default, to add a new pane on the right (“vertical split”) you would press ctrl+b (default prefix) and then release it and immediately press quotation mark ". For horizontal split, you would do ctrl+b and %

In my biased opinion, defaults are not ideal. I don’t find ctrl-b very convenient so I, and as far as I know many others, remap ctrl-b prefix to ctrl-space. I also can never remember " and “%” shortcuts so I remapped them to “h” for horizontal and “v” for vertical. Make life simpler, right?

So, those remappings and plugin configurations is what my config file ~/.tmux.config mostly is:

# -- Disable the default prefix key (Ctrl-b)
unbind C-b
# -- Set the new prefix key to Ctrl-Space
set -g prefix C-space

# -- terminal color support is essential for a good tmux experience, especially if you want to use themes and plugins that rely on colors.
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*256col*:Tc"


# -- Unbind the default split pane shortcuts to avoid conflicts with the new prefix key
# -- I can never remember these: (Ctrl-b + " and Ctrl-b + %) 
unbind '"'
unbind %

# --- split panes using h and v. h for horizontal and v for vertical splits. 
# -- Much easier to remember, in my opinion 
bind h split-window -h -c "#{pane_current_path}"
bind v split-window -v -c "#{pane_current_path}"
bind c new-window   -c "#{pane_current_path}"


set -g escape-time 10                      # stop vim feeling laggy
set -g history-limit 50000

# -- Reload the config file with prefix + r
unbind r
bind r source-file ~/.tmux.conf

# -- This is critical. It allows you to use the mouse to select panes, resize them, 
# -- and scroll through history. Without this, you have to use the keyboard to navigate 
# -- panes and scroll, which requires more shortcuts to remember. 
set -g mouse on
set -g default-terminal "tmux-256color"

# -- Tmux plugin manager allows easy installation of plugins and keeps them organized.
set -g @plugin 'tmux-plugins/tpm'
# -- List of essential plugins to install. You can add more plugins here as needed.
# -- tmux-sensible provides a set of default configurations that improve the user experience.
set -g @plugin 'tmux-plugins/tmux-sensible'
# -- tmux-resurrect allows you to save and restore tmux sessions, which is incredibly useful for maintaining your workflow across reboots or when you need to close your terminal.
set -g @plugin 'tmux-resurrect'
# -- tmux-continuum provides continuous saving of tmux sessions, complementing tmux-resurrect.
set -g @plugin 'tmux-continuum'
# -- tmux-yank allows you to copy text to the system clipboard easily.
set -g @plugin 'tmux-yank'

# -- status line is a critical part of the tmux experience that allows to quickly see the
#-- context of each pane as you switch between panes.  and catppuccin provides a 
#-- beautiful and functional status line that integrates well with the overall theme.

# -- Status line config with catppuccin
set -g @catppuccin_flavor "mocha"
set -g @catppuccin_window_status_style "rounded"
# -- make current directory in status line more readable by showing only the last part 
# --of the path, and replacing the home directory with ~. 
#-- This is especially useful when you have long paths, as it keeps the status line
#-- clean and easy to read.
set -g @home "$HOME"
set -g @catppuccin_directory_text ' #{s|/(.)[^/]+/|/\1/|g:#{s|/(.)[^/]+/|/\1/|g:#{s|^#{@home}|~|:#{pane_current_path}}}}'

run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux


set -g status-left-length 100

set -g status-left ""
set -ag status-left "#{E:@catppuccin_status_session}"
set -ag status-left "#{E:@catppuccin_status_directory}"

set -g status-right-length 100
set -g status-right ""
set -ag status-right "#{E:@catppuccin_status_user}"
set -ag status-right "#{E:@catppuccin_status_host}"
set -ag status-right "#{E:@catppuccin_status_uptime}"

run '~/.tmux/plugins/tpm/tpm'

Provisioning tmux for the first time

When you modify tmux config gile ~/.tmux.config you should run tmux source ~/.tmux.config so new settings get parsed. You can run this inside tmux session (if you dont want to restart) or outside

If you add a new plugin, you should also do prefix + Shift I, so with my settings: ctrl+space and shift+I

iTerm2 Considerations

If you are using iTerm2.app on MacOS, for Tmux to work well, you need to make sure couple configurations are set properly:

1. Settings -> General -> Tmux -> Clipboard

   make sure “Mirror tmux paste buffer” is checked/enabled!

2. Setttings -> Profiles -> your profile -> Terminal

   make sure all of the following are checked/enabled:

   1. Enable Mouse Reporting
   2. Report mouse wheel events
   3. Report mouse clicks & drags
   4. Terminal may enable alternate mouse scroll

Essential Shortcuts:

Reminder: prefix means ctrl+space in our config and default one is ctrl+b

prefix + z

Zoom in/out. If you have several panes and you want to make one of them “full screen” or go back to “see all panes” view

prefix + x

Close pane

prefix + h (overriden, default: prefix+")

Add new horizontal pane

prefix + v (overriden, default: prefix+%)

Add new vertical pane

prefix + d

Detach but keep tmux running so you can come back

Further Comfort

If you fall in love with tmux and decide ALL your terminal sessions MUST have tmux so you never accidentally end up in a shell without one, you can add this to your ~/.zshrc:

# In ~/.zshrc, near the top
if [[ -z "$TMUX" ]] && [[ -n "$PS1" ]] && [[ "$TERM_PROGRAM" == "iTerm.app" ]]; then
  tmux attach -t main 2>/dev/null || tmux new -s main
fi

Also, if you “hate” remembering common tmux commands, you can alias them (I know I do):

alias ta='tmux attach -t'
alias tls='tmux ls'
alias tn='tmux new -s'