Skip to content

🖥️ Tmux - Terminal Multiplexer

Tmux is the backbone of the terminal workflow, providing session management, window splitting, and seamless project switching.

📋 Table of Contents

🎯 Overview

Custom Prefix

  • Prefix Key: C-x (instead of default C-b)
  • Reason: Avoids conflicts with shell shortcuts and easier to reach

Key Features

  • Project Sessionizer: Quick project switching with FZF
  • Vim Navigation: Consistent hjkl movement across panes
  • Catppuccin Theme: Beautiful, consistent theming
  • Session Persistence: Automatic session management
  • Copy-Paste Integration: Seamless macOS clipboard integration

⌨️ Key Bindings

Session Management

Shortcut Action Description
C-x + t Project Sessionizer Open FZF project picker
C-x + E Wiki Session Quick access to wiki
C-x + X CNB Project Switch to CNB project
C-x + S NADR Project Switch to NADR project
C-x + D Mountain Project Switch to Mountain project
C-x + R CREPES Project Switch to CREPES project
C-x + G Infra Project Switch to infra project

Window & Pane Management

Shortcut Action Description
C-x + m Split Horizontal Create horizontal split
C-x + v Split Vertical Create vertical split
C-x + c New Window Create new window in current directory
C-x + h/j/k/l Navigate Panes Vim-style pane navigation
C-x + H/J/K/L Resize Panes Resize panes in direction
C-x + a Toggle Zoom Zoom current pane
C-x + A Next Pane Zoom Switch to next pane and zoom

Dev Prefix Mode (C-x g)

Shortcut Action Description
C-x g, 0-9 Jump Pane Select pane by index (zoom-aware)
C-x g, n Spawn Agent Create worktree + launch claude
C-x g, m Merge Worktree 2-phase merge into main
C-x g, c Cleanup Worktree Remove worktree (keep branch)
C-x g, d Delete All Remove worktree + delete branch
C-x g, w List Worktrees Show active agent worktrees
C-x g, q/Esc Exit Mode Return to normal

Layout Prefix Mode (C-x Backspace)

Shortcut Action Description
C-x Bspace, 1 Agentic Layout Chat + editor + 2 terminals
C-x Bspace, 2 2x2 Grid Four equal panes
C-x Bspace, 3 3x3 Grid Nine tiled panes

Copy Mode

Shortcut Action Description
C-x + [ Enter Copy Mode Start text selection
v Begin Selection Start selecting text (in copy mode)
y Copy Selection Copy selected text
C-x + ] Paste Paste copied text

Plugin Management

Shortcut Action Description
C-x + I Install Plugins Install new plugins
C-x + U Update Plugins Update existing plugins
C-x + alt + u Uninstall Plugins Remove unused plugins

🎯 Session Management

Creating Sessions

# Create new session
tmux new-session -s session_name

# Create session in specific directory
tmux new-session -s project -c ~/projects/my-project

# Create detached session
tmux new-session -d -s background_task

Attaching/Detaching

# List sessions
tmux list-sessions
tmux ls

# Attach to session
tmux attach-session -t session_name
tmux a -t session_name

# Detach from session
C-x + d

Session Navigation

# Switch between sessions
C-x + s    # Show session list
C-x + (    # Previous session
C-x + )    # Next session

🚀 Project Sessionizer

The project sessionizer is a powerful FZF-based tool for quick project switching.

How It Works

  1. Trigger: Press C-x + t or C-f (in Neovim)
  2. Search: FZF searches predefined project directories
  3. Select: Choose project with fuzzy search
  4. Switch: Automatically creates/switches to project session

Search Paths

~/personal
~/projects
~/work/cnb
~/work/cormac
~/work/mountain
~/work/timo

Usage Examples

# From anywhere, press C-x + t
# Type partial project name: "wiki"
# Press Enter to switch to wiki session

# Or use directly from command line
~/.local/bin/tmux-sessionizer ~/projects/my-project

Customization

Edit ~/.local/bin/tmux-sessionizer to add new search paths: 

search_paths=(
    ~/personal
    ~/projects
    ~/work/your-company
    ~/custom/path
)

🔌 Plugins

Plugin Manager: TPM

Installed Plugins

Core Plugins

  • tmux-sensible: Sensible default settings
  • tmux-fzf: FZF integration for tmux

Theme & UI

  • catppuccin-tmux: Beautiful Catppuccin theme
  • Custom status modules: Directory, meetings, date/time
  • tmux-easymotion: Vim-like easymotion for tmux
  • Trigger: Space key
  • Hints: asdghklqwertyuiopzxcvbnmfj

Plugin Management

Installing New Plugins

  1. Add plugin to ~/.tmux.conf: 
    set -g @plugin 'author/plugin-name'
  2. Press C-x + I to install
  3. Restart tmux or source config: C-x + r

Updating Plugins

# Update all plugins
C-x + U

# Or manually
cd ~/.tmux/plugins/tpm
git pull

Removing Plugins

  1. Remove/comment plugin line in config
  2. Press C-x + alt + u to uninstall
  3. Or manually delete from ~/.tmux/plugins/

⚙️ Configuration

Key Configuration Files

  • Main Config: dotfiles/tmux/.tmux.conf
  • Scripts: dotfiles/tmux/.config/tmux/scripts/

Important Settings

Terminal & Colors

set-option -g default-terminal "screen-256color"
set -ga terminal-overrides ",*:Tc"  # True color support
set -g allow-passthrough on         # Image preview support

Mouse & Navigation

set -g mouse on                     # Enable mouse support
setw -g mode-keys vi               # Vim keybindings
set -g base-index 1                # Start windows at 1
set -g renumber-windows on         # Renumber windows automatically

Performance

set-option -sg escape-time 5       # Faster escape for Neovim
set -g history-limit 10000         # Increase history
set-option -g focus-events on      # Enable focus events

Theme Configuration

# Catppuccin theme settings
set -g @catppuccin_window_left_separator ""
set -g @catppuccin_window_right_separator " "
set -g @catppuccin_status_modules_right "directory meetings date_time"
set -g @catppuccin_status_modules_left "session"
set -g @catppuccin_date_time_text "%H:%M"

Agent Workflow (tmux-agent)

Native dmux-inspired workflow for running Claude Code agents in isolated git worktrees.

Commands

tmux-agent spawn [prompt]           # Create worktree + launch claude in new pane
tmux-agent merge                    # 2-phase merge worktree → main
tmux-agent cleanup [--delete-branch] # Remove worktree + optionally delete branch
tmux-agent list                     # Show active agent worktrees

Keybindings (prefix+g = dev mode)

Shortcut Action Description
C-x g, n Spawn Agent Prompt for task, create worktree + pane
C-x g, m Merge 2-phase merge current worktree into main
C-x g, c Cleanup Remove current worktree (keep branch)
C-x g, d Delete Remove worktree + delete branch
C-x g, w List Show active agent worktrees

How It Works

  1. Spawn: Creates .worktrees/<slug> dir, agent/<slug> branch from main, opens tmux pane, launches claude with your prompt
  2. Work: Agent works in isolated worktree — no conflict with main branch
  3. Merge: First merges main→worktree (catch conflicts), then worktree→main
  4. Cleanup: Removes worktree directory, prunes git refs

Typical Workflow

# 1. Use Layout 1 for pane arrangement (prefix+backspace, 1)
# 2. Spawn agent in pane 1
C-x g, n → "fix authentication bug in login flow"

# 3. Agent works in isolated worktree...
# 4. When done, switch to agent pane and merge
C-x g, m

# 5. Cleanup worktree
C-x g, d

Worktree Structure

project/
├── .worktrees/           # Agent worktrees (gitignored)
│   ├── fix-auth-bug/     # Isolated copy for agent 1
│   └── add-api-cache/    # Isolated copy for agent 2
├── src/                  # Main working tree
└── ...

🔄 Workflows

Daily Development Workflow

  1. Start Day: C-x + t → Select main project
  2. Code: Use panes for editor, terminal, tests
  3. Switch Projects: C-x + t → Quick project switching
  4. End Day: Sessions persist automatically

Multi-Project Workflow

# Session 1: Main development
tmux new-session -d -s main -c ~/projects/main-project

# Session 2: Documentation
tmux new-session -d -s docs -c ~/projects/documentation

# Session 3: Monitoring/logs
tmux new-session -d -s monitoring

# Switch between them with C-x + s

Pair Programming Setup

# Create shared session
tmux new-session -d -s pair-session

# Both users attach to same session
tmux attach-session -t pair-session

🔧 Troubleshooting

Common Issues

Tmux Not Starting

# Check tmux version
tmux -V

# Kill all tmux sessions
tmux kill-server

# Start fresh
tmux new-session

Plugins Not Loading

# Reinstall TPM
rm -rf ~/.tmux/plugins/tpm
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# Reload config and install
tmux source-file ~/.tmux.conf
# Press C-x + I

Colors Not Working

# Check terminal color support
echo $TERM
echo $COLORTERM

# Test true color
curl -s https://gist.githubusercontent.com/lifepillar/09a44b8cf0f9397465614e622979107f/raw/24-bit-color.sh | bash

Copy-Paste Issues

# Install reattach-to-user-namespace (macOS)
brew install reattach-to-user-namespace

# Verify pbcopy/pbpaste work
echo "test" | pbcopy
pbpaste

Performance Issues

# Check session count
tmux list-sessions

# Kill unused sessions
tmux kill-session -t unused_session

# Reduce history limit if needed
set -g history-limit 5000

Configuration Debugging

# Reload configuration
tmux source-file ~/.tmux.conf

# Check configuration errors
tmux show-messages

# Verify key bindings
tmux list-keys

📚 Advanced Tips

Custom Scripts

Create custom scripts in ~/.config/tmux/scripts/: 

#!/bin/bash
# Example: Auto-layout for development
tmux split-window -h -p 30
tmux split-window -v -p 50
tmux select-pane -t 0

Session Templates

# Create session template script
#!/bin/bash
SESSION_NAME="dev-template"
tmux new-session -d -s $SESSION_NAME -c ~/projects

# Window 1: Editor
tmux rename-window "editor"
tmux send-keys "nvim" C-m

# Window 2: Terminal
tmux new-window -n "terminal" -c ~/projects

# Window 3: Server
tmux new-window -n "server" -c ~/projects
tmux send-keys "npm run dev" C-m

# Attach to session
tmux attach-session -t $SESSION_NAME

Integration with Other Tools

# Open tmux from Neovim
:terminal tmux new-session -d -s nested

# Use with SSH
ssh user@server -t tmux attach-session -t remote-dev