tmux-zsh

name: tmux-zsh description: Expert guidance for tmux terminal multiplexer and zsh shell configuration, design, and troubleshooting. Use when users need to configure tmux sessions, panes, keybindings, or plugins; set up zsh with vi-mode, plugins (zplug/zinit/oh-my-zsh), completions, or prompts (starship/powerlevel10k); integrate tmux and zsh with Nix/Home Manager; debug shell startup issues, keybinding conflicts, or plugin problems; or design productive terminal workflows.

Tmux & Zsh Configuration Skill

Overview

Expert knowledge for configuring tmux (terminal multiplexer) and zsh (Z shell) for productive terminal workflows.

Announce at start: "I'm using the tmux-zsh skill to help with terminal configuration."

Quick Diagnostics

Common Issues & Fixes

Zsh Configuration

Plugin Managers

Vi-Mode Integration

Critical pattern for starship + zsh-vi-mode:

# In initContent (before plugins)
ZVM_LAZY_KEYBINDINGS=false
ZVM_INIT_MODE=sourcing

function zvm_config() {
  ZVM_LINE_INIT_MODE=$ZVM_MODE_INSERT
  ZVM_VI_INSERT_ESCAPE_BINDKEY=jk
}

function zvm_after_init() {
  eval "$(starship init zsh)"
}

export FUNCNEST=500  # Prevent recursion errors

Essential Options

setopt HIST_IGNORE_ALL_DUPS  # No duplicate history entries
setopt SHARE_HISTORY         # Share history between sessions
setopt AUTO_CD               # cd into directories by typing name
setopt EXTENDED_GLOB         # Extended pattern matching
setopt NO_BEEP               # Silence terminal bell

Keybinding Modes

# Check current keymaps
bindkey -l

# Common modes:
# viins - vi insert mode (default for vi-mode)
# vicmd - vi command mode
# emacs - emacs mode

# Bind in specific mode
bindkey -M viins '^R' fzf-history-widget
bindkey -M vicmd 'v' edit-command-line

Tmux Configuration

Core Concepts

Essential Plugins (nixpkgs)

plugins = with pkgs.tmuxPlugins; [
  sensible        # Sane defaults
  yank            # Clipboard integration
  resurrect       # Session persistence
  continuum       # Auto-save/restore
  vim-tmux-navigator  # Seamless vim/tmux navigation
];

Keybinding Patterns

# Pane splits preserving path
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Vi-style pane resizing
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

# Vi copy mode
bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-selection

Session Management

# Create named session
tmux new-session -s work -c ~/projects

# Attach or create
tmux new-session -A -s main

# List sessions
tmux list-sessions

# Switch sessions
tmux switch-client -t <session>

Reference Files

• Tmux patterns: See references/tmux-patterns.md for advanced configuration patterns, plugin setup, and status bar customization
• Zsh patterns: See references/zsh-patterns.md for plugin ecosystems, completion systems, and prompt configuration
• Nix integration: See references/nix-integration.md for Home Manager module patterns and best practices

Debugging

Zsh Startup Profiling

# Add to ~/.zshrc
zmodload zsh/zprof

# Then run
zsh -i -c exit
zprof

Tmux Debug

# Show all keybindings
tmux list-keys

# Show all options
tmux show-options -g

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

# Check plugin loading
ls ~/.tmux/plugins/

Common Conflicts

Resources

• Tmux Manual: man tmux or https://man.openbsd.org/tmux
• Zsh Manual: man zshall or https://zsh.sourceforge.io/Doc/
• Home Manager Options: https://nix-community.github.io/home-manager/options.html