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.

bash

Add the following line to ~/.bashrc

# ~/.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

zsh

Add the following line to ~/.zprofile

# ~/.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

fish

Add the following line to ~/.config/fish/config.fish

# ~/.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:

bind-key J run-shell "t"

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:

Alacritty

Add the following line to your alacritty.yml

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

Kitty

Add the following line to your kitty.conf

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.

liiil825/t-smart-tmux-session-manager