# TPM - Tmux Plugin Manager TPM (Tmux Plugin Manager) is the plugin ecosystem for tmux. It lets you install, update, and manage tmux plugins with simple keybindings. **Series navigation:** 1. [[1. tmux Basics]] - Core concepts 2. [[2. tmux Configuration with chezmoi]] - Config management 3. **TPM - Tmux Plugin Manager** (this article) 4. [[4. Ghostty + tmux Startup Automation]] - Startup workflows 5. [[5. tmux Session Presets]] - Project layouts ## What It Does TPM manages tmux plugins, which extend tmux with features like: - **Session persistence** - Save and restore sessions (tmux-resurrect) - **Auto-save** - Automatic session backups (tmux-continuum) - **Sensible defaults** - Better keybindings out of the box (tmux-sensible) - **Copy improvements** - Better clipboard integration (tmux-yank) - **Pain control** - Better pane/window management (tmux-pain-control) ## How to Use It ### Installation **Homebrew (recommended):** ```bash brew install tmux tpm ``` Add to your Brewfile for portability: ```bash # Regenerate Brewfile brew bundle dump --file=~/Brewfile --force # Add to chezmoi chezmoi add ~/Brewfile ``` **Update `.tmux.conf` for Homebrew TPM:** ```bash # For Homebrew installation, use: run '/opt/homebrew/opt/tpm/share/tpm/tpm' # Or create symlink for standard path: mkdir -p ~/.tmux/plugins ln -s /opt/homebrew/opt/tpm/share/tpm ~/.tmux/plugins/tpm # Then use standard path: run '~/.tmux/plugins/tpm/tpm' ``` **Manual installation (alternative):** ```bash git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm ``` See [[2. Managing Homebrew with Brewfile]] for full Brewfile workflow. ### Adding Plugins Edit your `.tmux.conf`: ```bash # Add plugins set -g @plugin 'tmux-plugins/tpm' set -g @plugin 'tmux-plugins/tmux-sensible' set -g @plugin 'tmux-plugins/tmux-resurrect' # Initialize TPM (MUST be at the end) run '~/.tmux/plugins/tpm/tpm' ``` **Inside tmux, install plugins:** ``` Ctrl+B I ``` (That's capital I for "Install") ### Essential Keybindings | Keybinding | Action | |------------|--------| | `Ctrl+B I` | Install new plugins | | `Ctrl+B U` | Update plugins | | `Ctrl+B Alt+U` | Uninstall plugins not in config | ## Essential Plugins ### 1. tmux-sensible (Better Defaults) **What it does:** Fixes common tmux annoyances with sensible defaults. **Add to `.tmux.conf`:** ```bash set -g @plugin 'tmux-plugins/tmux-sensible' ``` **Features:** - Better scrollback history - More responsive keybindings - Improved mouse support - Better escape time settings ### 2. tmux-resurrect (Session Persistence) **What it does:** Save and restore tmux sessions manually. **Add to `.tmux.conf`:** ```bash set -g @plugin 'tmux-plugins/tmux-resurrect' ``` **Usage:** ``` # Save session Ctrl+B Ctrl+S # Restore session Ctrl+B Ctrl+R ``` **Configuration options:** ```bash # Restore Neovim sessions set -g @resurrect-strategy-nvim 'session' # Restore pane contents set -g @resurrect-capture-pane-contents 'on' # Restore directory set -g @resurrect-dir '~/.tmux/resurrect' ``` ### 3. tmux-continuum (Auto-Save Sessions) **What it does:** Automatically saves and restores sessions (uses tmux-resurrect). **Add to `.tmux.conf`:** ```bash set -g @plugin 'tmux-plugins/tmux-continuum' # Auto-restore sessions on tmux start set -g @continuum-restore 'on' # Save interval in minutes (default: 15) set -g @continuum-save-interval '15' ``` **Why use it:** Never manually save sessions again. Everything persists automatically! ### 4. tmux-yank (Better Copy/Paste) **What it does:** Improves copying to system clipboard. **Add to `.tmux.conf`:** ```bash set -g @plugin 'tmux-plugins/tmux-yank' ``` **Usage:** ``` # Enter copy mode Ctrl+B [ # Select text (Vim-style) v (start selection) y (copy to clipboard) # Or: Select with mouse, automatically copies! ``` **Configuration:** ```bash # Copy to macOS clipboard set -g @yank_selection_mouse 'clipboard' # Stay in copy mode after yanking set -g @yank_action 'copy-pipe' ``` ### 5. tmux-pain-control (Better Splits) **What it does:** Adds intuitive keybindings for pane management. **Add to `.tmux.conf`:** ```bash set -g @plugin 'tmux-plugins/tmux-pain-control' ``` **New keybindings:** | Keybinding | Action | |------------|--------| | `Ctrl+B \|` | Split vertically | | `Ctrl+B -` | Split horizontally | | `Ctrl+B h/j/k/l` | Navigate panes (Vim-style) | | `Ctrl+B H/J/K/L` | Resize panes | | `Ctrl+B <` | Swap pane left | | `Ctrl+B >` | Swap pane right | ## Recommended Plugin Setup Here's a solid starter plugin configuration for your `.tmux.conf`: ```bash # ============================================ # Plugins (Managed by TPM) # After applying config: # 1. Start tmux # 2. Press Ctrl+B I to install plugins # ============================================ # TPM itself set -g @plugin 'tmux-plugins/tpm' # Essential plugins set -g @plugin 'tmux-plugins/tmux-sensible' set -g @plugin 'tmux-plugins/tmux-resurrect' set -g @plugin 'tmux-plugins/tmux-continuum' set -g @plugin 'tmux-plugins/tmux-yank' # ============================================ # Plugin Configuration # ============================================ # tmux-resurrect: Save Neovim sessions set -g @resurrect-strategy-nvim 'session' set -g @resurrect-capture-pane-contents 'on' # tmux-continuum: Auto-save every 15 minutes set -g @continuum-restore 'on' set -g @continuum-save-interval '15' # tmux-yank: Copy to system clipboard set -g @yank_selection_mouse 'clipboard' # ============================================ # Initialize TPM (MUST be at the end) # ============================================ # For Homebrew TPM: run '/opt/homebrew/opt/tpm/share/tpm/tpm' # Or if you created the symlink: # run '~/.tmux/plugins/tpm/tpm' ``` ## Managing Plugins with Homebrew + chezmoi ### Pattern: TPM via Brewfile, Plugins Ignored **What to manage:** - ✅ `.tmux.conf` (contains plugin list) - in chezmoi - ✅ `tmux` and `tpm` packages - in Brewfile - ✅ Brewfile itself - in chezmoi **What NOT to manage:** - ❌ `~/.tmux/plugins/*` (Git repos, regenerated by TPM) ### Setup **1. Add `.tmux.conf` to chezmoi:** ```bash chezmoi add ~/.tmux.conf ``` **2. Tell chezmoi to ignore plugin directory:** ```bash echo ".tmux/plugins/*" >> ~/.local/share/chezmoi/.chezmoiignore ``` **3. Create TPM auto-install script (shown above)** **4. Commit:** ```bash cd ~/.local/share/chezmoi git add . git commit -m "Add tmux config with TPM setup" git push ``` ### On a New Machine ```bash # Apply chezmoi config (installs TPM automatically) chezmoi apply # Start tmux tmux # Install plugins Ctrl+B I ``` Done! Your plugins are now installed. ## Advanced: Plugin Development You can create custom plugins! TPM plugins are just shell scripts. **Structure:** ``` ~/.tmux/plugins/my-plugin/ ├── my-plugin.tmux # Main script └── scripts/ └── helper.sh # Helper scripts ``` **Example plugin** (`my-plugin.tmux`): ```bash #!/usr/bin/env bash CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" # Your plugin logic here tmux set-option -g status-right "Custom status" ``` **Add to `.tmux.conf`:** ```bash set -g @plugin 'yourusername/my-plugin' ``` See [TPM documentation](https://github.com/tmux-plugins/tpm) for details. ## Troubleshooting ### Plugins not installing **Check TPM is installed:** ```bash ls ~/.tmux/plugins/tpm ``` If missing, install: ```bash git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm ``` **Inside tmux, try:** ``` Ctrl+B I ``` ### Plugins not loading **Check `.tmux.conf` has TPM initialization:** ```bash grep "tpm/tpm" ~/.tmux.conf ``` Should show: ```bash run '~/.tmux/plugins/tpm/tpm' ``` **This MUST be at the end of `.tmux.conf`!** **Reload config:** ```bash tmux source ~/.tmux.conf ``` ### Updates not working **Update TPM itself:** ```bash cd ~/.tmux/plugins/tpm git pull ``` **Update plugins:** ``` Ctrl+B U ``` ### Session restore not working (tmux-resurrect) **Check save directory exists:** ```bash ls ~/.tmux/resurrect/ ``` **Manually save:** ``` Ctrl+B Ctrl+S ``` **Check if auto-restore is enabled:** ```bash grep "continuum-restore" ~/.tmux.conf ``` Should show: ```bash set -g @continuum-restore 'on' ``` ## Next Steps - [[4. Ghostty + tmux Startup Automation]] - Auto-start tmux with plugins loaded - [[5. tmux Session Presets]] - Use plugins with preset layouts - [[2. tmux Configuration with chezmoi]] - Manage plugin config across machines **Related:** - [TPM GitHub](https://github.com/tmux-plugins/tpm) - [Plugin List](https://github.com/tmux-plugins/list)