Tmux Workflow

Plugin Lifecycle

# Add plugin to tmux.conf
set -g @plugin 'author/plugin-name'

Adding a New Plugin

1. Add set -g @plugin 'author/plugin' to tmux.conf
2. Press prefix + I (Capital I) to install
3. Plugin is cloned to ~/.config/tmux/plugins/

Removing a Plugin

1. Delete/comment the set -g @plugin line in tmux.conf
2. Press prefix + Alt + u to clean up

Current Plugins

Catppuccin Theme Configuration

Basic Setup

set -g @catppuccin_flavor 'macchiato'
set -g @catppuccin_window_status_style 'rounded'

Window Styling

set -g @catppuccin_window_default_fill "number"
set -g @catppuccin_window_default_text " #W"
set -g @catppuccin_window_current_fill "number"
set -g @catppuccin_window_current_text " #W"
set -g @catppuccin_window_current_color "#{@thm_mauve}"

Status Bar

set -g @catppuccin_status_left_separator "█"
set -g @catppuccin_status_right_separator "█"
set -g @catppuccin_status_modules_left "session"
set -g @catppuccin_status_modules_right "cpu memory date_time"

Pane Borders

set -g @catppuccin_pane_border_style "fg=#{@thm_surface1}"
set -g @catppuccin_pane_active_border_style "fg=#{@thm_mauve}"

Date/Time Format

set -g @catppuccin_date_time_text "%H:%M"

Theme Color Variables

Available via #{@thm_*}:

#{@thm_rosewater}  #{@thm_flamingo}  #{@thm_pink}
#{@thm_mauve}      #{@thm_red}       #{@thm_maroon}
#{@thm_peach}      #{@thm_yellow}    #{@thm_green}
#{@thm_teal}       #{@thm_sky}       #{@thm_sapphire}
#{@thm_blue}       #{@thm_lavender}
#{@thm_text}       #{@thm_subtext1}  #{@thm_subtext0}
#{@thm_overlay2}   #{@thm_overlay1}  #{@thm_overlay0}
#{@thm_surface2}   #{@thm_surface1}  #{@thm_surface0}
#{@thm_base}       #{@thm_mantle}    #{@thm_crust}

Custom Module Development

Module Location

Custom modules live in config/tmux/custom_modules/:

• ctp_cpu.conf — CPU usage display
• ctp_memory.conf — Memory usage display
• primary_ip.conf — Primary IP address display

Module Format

Modules are sourced tmux config files containing format strings:

# Example: custom_modules/ctp_cpu.conf
set -g @catppuccin_cpu_icon " "
set -g @catppuccin_cpu_color "#{@thm_green}"
set -g @catppuccin_cpu_text "#(top -bn1 | grep 'Cpu(s)' | awk '{print $2}')%"

Dynamic Content with #()

Use #() to run shell commands in status bar:

# Run command every status-interval seconds
set -g status-right "#(whoami)@#(hostname)"

# Complex script
set -g status-right "#(~/.config/tmux/scripts/status.sh)"

Format String Variables

Conditional Formats

# Show icon if zoomed
set -g @catppuccin_window_current_text "#{?window_zoomed_flag,🔍 ,}#W"

# Alert for prefix
set -g @catppuccin_status_modules_left "#{?client_prefix,#[bg=#{@thm_red}] PREFIX ,session}"

Recommended Additional Plugins

Session Persistence

# Save/restore sessions across restarts
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'

set -g @resurrect-capture-pane-contents 'on'
set -g @continuum-restore 'on'
set -g @continuum-save-interval '15'    # Auto-save every 15 min

Text Selection

# Vimium-like text selection (press prefix + space to activate)
set -g @plugin 'fcsonline/tmux-thumbs'
set -g @thumbs-command 'echo -n {} | wl-copy'   # Wayland clipboard

# Alternative: tmux-fingers
set -g @plugin 'Morantron/tmux-fingers'

Session Management

# FZF-powered session manager
set -g @plugin 'omerxx/tmux-sessionx'
set -g @sessionx-bind 'o'              # prefix + o to open
set -g @sessionx-zoxide-mode 'on'      # Use zoxide for paths

Floating Terminal

# Toggle floating pane
set -g @plugin 'omerxx/tmux-floax'
set -g @floax-bind 'p'                 # prefix + p to toggle
set -g @floax-width '80%'
set -g @floax-height '80%'

Keybind Patterns

Pane Navigation (vim-tmux-navigator)

Pane Management

# Split panes (using current path)
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Resize panes (repeatable with -r)
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

# Zoom (toggle maximize)
bind -r m resize-pane -Z

Window Management

Session Management

Copy Mode (vi keys)

setw -g mode-keys vi

bind-key -T copy-mode-vi v send -X begin-selection
bind-key -T copy-mode-vi y send -X copy-pipe-and-cancel 'wl-copy'
bind-key -T copy-mode-vi C-v send -X rectangle-toggle

Which-Key Discovery

Press prefix + Space to open the which-key menu showing all available keybinds organized by category.

Session Workflow Patterns

Development Session

# Create or attach to dev session
tmux new-session -A -s dev -c ~/Developer/github/project

# Layout: editor (large) + terminal (small)
# Tab 1: Editor
# Tab 2: Terminal
# Tab 3: Git (lazygit)

Monitoring Session

tmux new-session -A -s monitor

# Tab 1: btop (system monitor)
# Tab 2: Docker logs
# Tab 3: journalctl -f

Scripted Session Setup

#!/bin/zsh
SESSION="project"

tmux has-session -t "$SESSION" 2>/dev/null
if [ $? != 0 ]; then
    tmux new-session -d -s "$SESSION" -c ~/Developer/github/project

    tmux rename-window -t "$SESSION:0" "editor"
    tmux send-keys -t "$SESSION:0" "nvim ." C-m

    tmux new-window -t "$SESSION" -n "terminal"

    tmux new-window -t "$SESSION" -n "git"
    tmux send-keys -t "$SESSION:2" "lazygit" C-m

    tmux select-window -t "$SESSION:0"
fi
tmux attach -t "$SESSION"

Per-Project Sessions

Name sessions after projects for quick switching:

tmux new-session -s dotfiles -c ~/Developer/github/.dotfiles
tmux new-session -s webapp -c ~/Developer/github/webapp

Switch between: prefix + s → select with fzf (tmux-fzf) or arrow keys.

General Configuration Tips

True Color Support

set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

Mouse Support

set -g mouse on

Base Index

set -g base-index 1          # Windows start at 1
setw -g pane-base-index 1    # Panes start at 1
set -g renumber-windows on   # Re-number on close

History

set -g history-limit 50000

Status Bar Refresh

set -g status-interval 5     # Refresh every 5 seconds