t - the smart tmux session manager

tmux is a powerful tool, but dealing with sessions can be painful. This script makes it easy to create and switch tmux sessions:

Prerequisites

• tmux
• tpm
• zoxide
• fzf (>=0.35.0)
• fd (optional)

How to install

1. Install tpm plugin

Add the following line to your tmux.conf file:

set -g @plugin 'joshmedeski/t-smart-tmux-session-manager'

Note: tpm recommends you list your plugins and then run tpm at the very bottom of your tmux.conf.

Then, run <prefix>I to install the plugin.

2. Add to path

To use the t script from anywhere, select your shell environment and follow the instructions.

Note: you'll need to check the path of your tpm plugins. It may be ~/.tmux/plugins or ~/.config/tmux/plugins depending on where your tmux.conf is located.

# ~/.tmux/plugins
export PATH=$HOME/.tmux/plugins/t-smart-tmux-session-manager/bin:$PATH
# ~/.config/tmux/plugins
export PATH=$HOME/.config/tmux/plugins/t-smart-tmux-session-manager/bin:$PATH

# ~/.tmux/plugins
export PATH=$HOME/.tmux/plugins/t-smart-tmux-session-manager/bin:$PATH
# ~/.config/tmux/plugins
export PATH=$HOME/.config/tmux/plugins/t-smart-tmux-session-manager/bin:$PATH

# ~/.tmux/plugins
fish_add_path $HOME/.tmux/plugins/t-smart-tmux-session-manager/bin
# ~/.config/tmux/plugins
fish_add_path $HOME/.config/tmux/plugins/t-smart-tmux-session-manager/bin

3. Recommended tmux settings

I recommend you add these settings to your tmux.conf to have a better experience with this plugin.

bind-key x kill-pane # skip "kill-pane 1? (y/n)" prompt
set -g detach-on-destroy off  # don't exit from tmux when closing a session

4. Customize Prompt (optional)

If your terminal supports Nerd Font symbols, you can customize your prompt.

set -g @t-fzf-prompt '  '

Or you can replace the prompt with anything you'd like.

How to use

  Run interactive mode
      t
        ctrl-s list only tmux sessions
        ctrl-x list only zoxide results
        ctrl-d list directories

  Go to session (matches tmux session, zoxide result, or directory)
      t {name}

  Open popup (while in tmux)
      <prefix>+T
        ctrl-s list only tmux sessions
        ctrl-x list only zoxide results
        ctrl-d list directories

  Show help
      t -h
      t --help

By default, this plugin is bound to <prefix>+T which triggers a fzf-tmux popup that display zoxide results. Type the result you want and when you hit enter it will create a tmux session and connect to it or, if the sessions already exists, switch to it.

If you are not in tmux, you can simply run t to start the interactive script, or call t {name} to jump directly to a session of your choosing.

Key Bindings

• ctrl-s list only tmux sessions
• ctrl-x list only zoxide results
• ctrl-d list directories (or find if fd isn't installed)

How to add a custom keybinding

In order to add your own custom key binding to trigger the t script, add the following to your tmux.conf:

set -g @t-bind "J"

You can unbind the default by entering an unmappable string (e.g. none)

Background

Interested in learning more about how this script came to be? Check out Smart tmux sessions with zoxide and fzf. ]

Bonus: macOS keyboard shortcut

My personal workflow uses macOS Keyboard Shortcuts for tmux. I have bound the t popup to cmd+j with the following code:

key_bindings:
  - { key: J, mods: Command, chars: "\x02\x54" } # open t - tmux smart session manager

map cmd+j send_text all \x02\x54

Note: These bindings are based off the default prefix, ctrl+b (which converts to \x02). If you changed your prefix, I recommend watching my video which goes into depth how to customize your own keybindings in Alacritty.