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
| Symptom |
Likely Cause |
Fix |
| Slow shell startup |
Plugin overhead |
Profile with zsh -xv or zprof |
| Vi-mode breaks prompt |
Starship/zvm conflict |
Configure ZVM_INIT_MODE=sourcing |
| Keybindings not working |
Wrong binding mode |
Check bindkey -l and mode (viins/vicmd) |
| Tmux colors wrong |
TERM not set |
Use TERM=screen-256color or tmux-256color |
| Copy/paste broken |
Clipboard integration |
Configure set -g @yank_selection_mouse 'clipboard' |
| Resurrect not restoring |
Save path issues |
Check ~/.tmux/resurrect/ permissions |
Zsh Configuration
Plugin Managers
| Manager |
Config Style |
Best For |
| zplug |
Nix-native |
Home Manager integration |
| zinit |
Turbo mode |
Performance-focused |
| oh-my-zsh |
Framework |
Beginners, comprehensive themes |
| antigen |
Bundle-based |
Simple setup |
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
| Concept |
Description |
| Session |
Top-level container, persists detached |
| Window |
Tab within session |
| Pane |
Split within window |
| Prefix |
Key combo to trigger tmux commands (default: C-b) |
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
| Tool A |
Tool B |
Issue |
Resolution |
| zsh-vi-mode |
starship |
Infinite recursion |
Use zvm_after_init hook |
| fzf |
atuin |
Ctrl-R conflict |
Choose one or rebind |
| tilish |
vim-tmux-navigator |
C-hjkl conflict |
Configure @tilish-navigate |
| tmux |
ghostty |
Terminal capabilities |
Set proper TERM |
Resources
zach-source