TPM - Tmux Plugin Manager

Path: Computer Tech/Terminal/tmux/TPM - Tmux Plugin Manager.mdUpdated: 2/3/2026

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:

tmux Basics - Core concepts
tmux Configuration with chezmoi - Config management
TPM - Tmux Plugin Manager (this article)
Ghostty + tmux Startup Automation - Startup workflows
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 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↗ 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

Ghostty + tmux Startup Automation - Auto-start tmux with plugins loaded
tmux Session Presets - Use plugins with preset layouts
tmux Configuration with chezmoi - Manage plugin config across machines

Related: