Features

Manage sessions (switch, new, rename, detach, kill).
Manage windows (switch, link, move, swap, rename, kill).
Manage panes (switch, break, join, swap, layout, kill, resize).
Search commands and append to command prompt.
Search key bindings and execute.
Search clipboard history and paste to current window.
Process management (top, pstree, terminate, kill, interrupt, continue, stop, quit, hangup).
User menu (run custom commands).
Preview sessions, windows and panes.
Multiple selection.

Installation

Requirements

GNU bash
sed
junegunn/fzf
CopyQ (optional): Access system clipboard, fallback to builtin tmux buffers if copyq is not executable.
pstree (optional): Display process tree.

Note: Please use this command to check whether tmux is able to find fzf #1: tmux run-shell -b 'command -v fzf'

Install via TPM

Add this line to your ~/.tmux.conf

set -g @plugin 'sainnhe/tmux-fzf'

Reload configuration, then press prefix + I.

Usage

To launch tmux-fzf, press prefix + F (Shift+F).

This plugin supports multiple selection for some actions, you can press TAB and Shift-TAB to mark multiple items.

Most of the features work out of the box, but there are some features that need to be explained here.

Kill Window(s)

The kill action in tmux-fzf actually uses tmux unlink-window -k instead of tmux kill-window.

The main difference between unlink-window -k and kill-window is that kill-window will kill current window and all other windows linked to it, while unlink-window -k will only kill current window.

The logic of unlink -k is a bit like hard links. If the current window only exists in one session, then kill; if the current window exists in multiple sessions, then unlink.

Btw, if you want to bind a key to kill current window, I would recommend unlink-window -k instead of kill.

User Menu

You can add a custom menu to quickly execute some commands.

This feature is not enabled by default. To enable it, add something like this to ~/.tmux.conf

TMUX_FZF_MENU=\
"foo\necho 'Hello!'\n"\
"bar\nls ~\n"\
"sh\nsh ~/test.sh\n"

When you launch tmux-fzf, an extra item named menu will appear. Selecting this item will produce this.

There will be 3 items to select from: foo, bar and sh.

When you select foo, tmux will execute echo 'Hello!'.

When you select bar, tmux will execute ls ~.

When you select sh, tmux will execute sh ~/test.sh.

Note:

foo and echo 'hello' are separated by \n in TMUX_FZF_MENU, and you need to add another \n after echo 'hello'.
DO NOT add additional white spaces/tabs at the beginning of each line.
Commands are executed using tmux -c, so please make sure tmux -c "your command" does work.

Popup Window

Popup window is a new feature introduced in tmux 3.2 . To enable this feature, you'll need to have tmux >= 3.2 installed.

This feature is automatically enabled in tmux >= 3.2, but you can disable it using $TMUX_FZF_OPTIONS, see Fzf Behavior.

Customization

Key Binding

For example, to use prefix + C-f (Ctrl+F), add this line to your ~/.tmux.conf

TMUX_FZF_LAUNCH_KEY="C-f"

Fzf Behavior

This plugin will read fzf environment variables, so you can use these variables to customize the behavior of fzf (e.g. prompt and color).

In addition, this plugin supports customizing the options of fzf-tmux command which is bundled with fzf, you can customize them by adding something like this to ~/.tmux.conf

# Default value in tmux < 3.2
TMUX_FZF_OPTIONS="-m"

# Default value in tmux >= 3.2
TMUX_FZF_OPTIONS="-p -w 62% -h 38% -m"

To list all available options of fzf-tmux, execute ~/.tmux/plugins/tmux-fzf/scripts/.fzf-tmux --help in your shell.

Preview

Preview is enabled by default. To hide it, add something like this to your ~/.tmux.conf:

TMUX_FZF_PREVIEW=0

Then the preview window will be hidden until toggle-preview is triggered.

By default, the preview window will try to "follow" the content (see description in the fzf docs). You can opt out this behavior using the following:

TMUX_FZF_PREVIEW_FOLLOW=0

Order

To customize the order of the actions, add something like this to your ~/.tmux.conf:

TMUX_FZF_ORDER="session|window|pane|command|keybinding|clipboard|process"

You can also use this variable to disable unwanted features. For example, to disable clipboard and process, simply delete them in $TMUX_FZF_ORDER:

TMUX_FZF_ORDER="session|window|pane|command|keybinding"

Format

For some reasons, you may want to customize format of panes, windows, sessions listed in fzf. There are three variables to complete this work:

TMUX_FZF_PANE_FORMAT TMUX_FZF_WINDOW_FORMAT TMUX_FZF_SESSION_FORMAT

For example, tmux list-panes -a doesn't show running program and window name by default. If you want to show running program and window name, add something like this to ~/.tmux.conf

TMUX_FZF_PANE_FORMAT="[#{window_name}] #{pane_current_command}  [#{pane_width}x#{pane_height}] [history #{history_size}/#{history_limit}, #{history_bytes} bytes] #{?pane_active,[active],[inactive]}"

Similarly, TMUX_FZF_WINDOW_FORMAT and TMUX_FZF_SESSION_FORMAT can also be handled in this way.

For more information, check "FORMATS" section in tmux manual.

Filter

By default, the current session, window, and pane, are not listed among the switch possibilities. To include it, set:

TMUX_FZF_SWITCH_CURRENT=1

When using the window listing script, it is possible to filter its output. This relies on the tmux filtering feature with a specific syntax for filters. For more information about this feature, check "FORMATS" section in the tmux manual.

To use this filtering feature, set the variable TMUX_FZF_WINDOW_FILTER to the filter you want to apply before calling the window.sh script.

FAQ

Q: Why use environment variables instead of tmux options to customize this plugin?

A: Because the performance of tmux options is very bad. I pushed a branch named tmux-options to demonstrate how bad the performance will be if we use tmux options to customize this plugin, you can checkout this branch and get it a try.

Q: How to launch tmux-fzf with preselected action?

A: See #6.

Q: What's your status line configuration?

A: See this post.

Q: What's the color scheme used in the screenshot?

A: Gruvbox Material

More plugins

sainnhe/tmux-translator: A translation plugin powered by popup window.

License

The code of /scripts/.fzf-tmux is copied from junegunn/fzf which is licensed under MIT.

Other code is distributed under MIT && Anti-996.

sainnhe / tmux-fzf