Tmux Session Management Skill

Overview

This system uses tmux with tmuxinator templates and sesh for powerful session management.

Configuration Locations

• Tmuxinator templates: ~/.config/tmuxinator/*.yml
• Tmux config: ~/.tmux.conf
• Zsh tmux aliases/functions: ~/.zshrc (lines 37-72)
• Active sessions: Check with tmux ls or sesh list

Tmuxinator Templates

Current Templates

1. default.yml - Flexible project template

   • Takes directory argument: tmuxinator start default ~/path
   • Layout: nvim (top 70%), terminal + claude (bottom)
   • Dynamic session naming based on directory

2. admin.yml - System monitoring

   • Fixed name: "admin"
   • Layout: btop (left column), 2 terminals (right)
   • Purpose: System monitoring and administration

3. config.yml - Dotfiles editing

   • Fixed name: "config"
   • Root: ~/.config
   • Layout: nvim (top 70%), terminal + claude (bottom)

Template Structure

CRITICAL: Pane Indexing
This tmux configuration uses 1-based indexing (set in ~/.tmux.conf):

set -g base-index 1        # Windows start at 1
set -g pane-base-index 1   # Panes start at 1

• First pane = 1, second = 2, third = 3
• Use prefix + q (Ctrl+Space then q) to see pane numbers visually
• When targeting panes in commands: select-pane -t 1 (not -t 0)

Tmuxinator YAML Structure:

---
name: session-name  # Fixed name (or use <%= File.basename(...) %> for dynamic)
root: ~/path        # Working directory

on_project_start: tmux resize-pane -t name:0.0 -y 70%  # Optional startup commands

windows:
  - window-name:
      layout: main-horizontal  # or main-vertical, tiled, even-horizontal, etc.
      panes:
        - nvim                 # Command to run in pane 1
        - # empty terminal     # Empty pane (interactive shell) - pane 2
        - claude --resume      # Command for pane 3

Shell Function Structure (for creating windows dynamically):

tnw() {
  # Get the session's root directory (uses 1-based indexing internally)
  local session_path=$(tmux display-message -p '#{session_path}')

  tmux new-window -c "$session_path" \; \
    split-window -v -c "$session_path" \; \
    split-window -v -c "$session_path" \; \
    select-layout main-horizontal \; \
    select-pane -t 1 \; \
    send-keys 'nvim' C-m \; \
    select-pane -t 3 \; \
    send-keys 'claude --resume' C-m \; \
    select-pane -t 2
}

Key points for both:

• Use #{session_path} to get session root directory (not current pane path)
• Pane indexing is 1-based: first pane = 1, not 0
• send-keys 'command' C-m executes commands in panes (C-m = Enter)
• select-pane -t N focuses pane N (1-based)
• select-layout applies tmux built-in layouts

Common Layouts

• main-horizontal - Top pane large, others stacked below
• main-vertical - Left pane large, others stacked right
• tiled - All panes equal size
• even-horizontal - Panes side-by-side equal width
• even-vertical - Panes top-to-bottom equal height

Session Management with ts (tmux session selector)

The ts function (defined in ~/.zshrc) is the main session switcher:

ts  # Opens fzf with: "home" + tmuxinator templates + active sessions

How ts Works

1. Lists all tmuxinator templates (except default.yml)
2. Adds "home" as an option
3. Shows all active tmux sessions from sesh list
4. On selection:
   • If session exists → attach with sesh connect
   • If tmuxinator template exists → tmuxinator start <template>
   • Otherwise → tmuxinator start default <name> (creates new project session)

Key Insight

Template names come from the filename (e.g., admin.yml → "admin" in fzf), but the actual tmux session name comes from the name: field in the YAML file.

Tmux Functions & Aliases

From ~/.zshrc:

Session Management

ts          # Tmux session selector (fzf for sessions/templates)
tns <name>  # Tmux new session - create git project & open with tmuxinator
t [name]    # Smart attach/create - attach if exists, create if not
ta <name>   # Attach to session
tn <name>   # Create new session
tls         # List sessions
tk <name>   # Kill session

Window Management

tnw         # Tmux new window - create window with 3-pane layout
            # Layout: pane 1=nvim, pane 2=terminal (focused), pane 3=claude
            # Bound to: prefix + N

Utilities

tcopy       # Copy tmux buffer to clipboard
tlines [n]  # Copy last n lines from tmux pane to clipboard

Common Workflows

Starting Sessions

ts                                        # Use fzf to select session/template
tns myproject                             # Create ~/git/myproject with git + tmuxinator
tns myproject config                      # Use 'config' template instead of default
tmuxinator start admin                    # Start admin monitoring
tmuxinator start config                   # Edit dotfiles
tmuxinator start default ~/git/myproject  # New project session with default template

Creating Windows

tnw                # Create new window with 3-pane layout in current session
prefix + N         # Keybinding for tnw (Ctrl+Space then Shift+N)
prefix + c         # Create empty new window (default tmux)
prefix + ,         # Rename current window

Creating New Templates

1. Create ~/.config/tmuxinator/name.yml
2. Use existing templates as reference
3. Test with tmuxinator start name
4. Now available in sf automatically

Auto-Start Behavior

On terminal startup (from ~/.zshrc:272-275):

• Creates "home" session if it doesn't exist
• Runs in background (detached)
• Provides a default session to attach to

Best Practices

1. Fixed names for utilities: Use name: admin for consistent session names
2. Dynamic names for projects: Use <%= File.basename(...) %> for project-based naming
3. Exclude default from sf: The default template is a fallback, not a session target
4. Keep layouts simple: 2-3 panes max for usability
5. Use comments for empty panes: # interactive shell for clarity

Troubleshooting

• Wrong session name: Check name: field in YAML vs filename
• Template not showing in sf: Ensure .yml extension and not named "default"
• Layout issues: Try tmux kill-session -t name and restart
• Pane sizes: Use on_project_start with tmux resize-pane commands