# Tmux Plugins

**Plugins** extend tmux with additional functionality. They can add new key bindings, status bar enhancements, pane themes, and more. Plugins are shell scripts that hook into tmux's configuration. The easiest way to manage them is with a plugin manager like TPM (Tmux Plugin Manager).

## TPM (Tmux Plugin Manager)

TPM is the standard plugin manager for tmux. Clone it into `~/.tmux/plugins/tpm`:

```bash
$ git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
```

Then source it in `~/.tmux.conf`:

```
# List plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'

# Initialize TPM (keep this line at the very end of tmux.conf)
run '~/.tmux/plugins/tpm/tpm'
```

Install or update plugins by pressing `Ctrl+B I` (capital I). Remove plugins by deleting them from the config and pressing `Ctrl+B Alt+U`.

## Common plugins

**tmux-sensible** — sensible defaults that most users want (mouse support, vi keys in copy mode, better scrollback):

```
set -g @plugin 'tmux-plugins/tmux-sensible'
```

**tmux-resurrect** — save and restore tmux sessions across reboots:

```
set -g @plugin 'tmux-plugins/tmux-resurrect'
```

Press `Ctrl+B Ctrl+S` to save session state. Press `Ctrl+B Ctrl+R` to restore. Useful for long-running work that spans machine reboots.

**tmux-continuum** — automatically save sessions at intervals and restore on startup:

```
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-save-interval '15'  # save every 15 minutes
set -g @continuum-restore 'on'        # auto-restore on tmux startup
```

Requires tmux-resurrect as a dependency.

**tmux-prefix-highlight** — highlight status bar when prefix key is pressed:

```
set -g @plugin 'tmux-plugins/tmux-prefix-highlight'
set -g status-right '#{prefix_highlight} | %H:%M'
```

**tmux-yank** — copy to system clipboard in copy mode. Use `y` to copy in vi copy mode:

```
set -g @plugin 'tmux-plugins/tmux-yank'
```

## Writing a custom plugin

A plugin is a shell script sourced in `~/.tmux.conf`. Create `~/.tmux/plugins/my-plugin/my-plugin.tmux`:

```bash
#!/bin/bash

# Bind a custom key
tmux bind-key -n C-h send-keys "echo 'hello'" Enter

# Add status bar variable
tmux set-environment -g my_var "custom_value"
```

Then add it to `~/.tmux.conf`:

```
set -g @plugin '~/.tmux/plugins/my-plugin'
```

Plugins receive the TPM install/update/remove lifecycle hooks via script arguments. Check the TPM documentation for details on plugin development.

## Finding plugins

Browse community plugins on GitHub under the [tmux-plugins](https://github.com/tmux-plugins) organization. Most follow the naming convention `tmux-<name>`.