• tmux (>= 3.2)
• tpm
• zoxide
• fzf (>=0.35.0)

Note: some users have had issues with fzf integration on tmux 3.2a where upon spawning fzf it would lock the tmux pane. Upgrading to 3.3a seems to be a viable workaround Check #104

brew install tmux zoxide fzf

Use the package manager of your OS if you are not on macOS.

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.

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

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

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.

  Run interactive mode
      t
        ctrl-s list only tmux sessions
        ctrl-x list only zoxide results
        ctrl-f list results from the find command

  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-f list results from the find command

  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.

• ctrl-s list only tmux sessions
• ctrl-x list only zoxide results
• ctrl-f find by directory

You can quickly clone a repository to your preferred directory by using the t command combined with the -r flag (or --repo).

First, you have to set the T_REPOS_DIR variable in your shell environment. Make sure to set it where you want your repositories cloned.

export T_REPOS_DIR="~/repos"

export T_REPOS_DIR="~/repos"

set -Ux T_REPOS_DIR ~/repos

In order to use the feature, simply run:

t -r https://github.com/joshmedeski/t-smart-tmux-session-manager.git

Note: it has to be a valid git remote url (ending in .git) or order to work.

I prefer to copy the repository URL to my clipboard and run the following command on macOS.

t -r $(pbpaste)

t -r (pbpaste)

If you want to overwrite the directory to clone to, you can overwrite the T_REPOS_DIR variable before running the command:

T_REPOS_DIR=~/code t --repo https://github.com/joshmedeski/tmux-list.git

You may prefer your session names starting from the root of the git repository. This can help with naming conflicts if you have multiple directories with the same name on your machine and make it clear when you have multiple sessions open in the same git repository.

export T_SESSION_USE_GIT_ROOT="true"

export T_SESSION_USE_GIT_ROOT="true"

set -Ux T_SESSION_USE_GIT_ROOT true

You may prefer your session names having a prefix of the parent directory. This can help with naming conflicts if you have multiple directories with the same name on your machine.

export T_SESSION_NAME_INCLUDE_PARENT="true"

export T_SESSION_NAME_INCLUDE_PARENT="true"

set -Ux T_SESSION_NAME_INCLUDE_PARENT true

By default, the t popup is bound to <prefix>T. In order to overwrite your own custom key binding, add setting the @t-bind varaible to your tmux.conf:

set -g @t-bind "K"

You can unbind the default by using none.

set -g @t-bind "none" # unbind default

By default, t will display tmux sessions and zoxide results by default. You can change this by setting @t-fzf-default-results variable to your tmux.conf:

set -g @t-fzf-default-results 'sessions' # show tmux sessions by default

set -g @t-fzf-default-results 'zoxide' # show zoxide results by default

By default, the find key binding (^f) will run a simple find command to search for directories in and around your home directory.

find ~ -maxdepth 3 -type d

You can customize this command by setting @t-find-binding variable to your tmux.conf:

In this example, I'm setting the prompt with a custom Nerd Font icon and using fd to search directories (including hidden ones) up to two levels deep from my home directory.

set -g @t-fzf-find-binding 'ctrl-f:change-prompt(  )+reload(fd -H -d 2 -t d . ~)'

Run man fzf to learn more about how to customize key bindings with fzf.

If you want to overwrite the fzf-tmux options, you can set the FZF_TMUX_OPTS variable in your shell environment.

# ~/.bashrc or ~/.zshrc
export FZF_TMUX_OPTS="-p 55%,60%"

# ~/.config/fish/config.fish
set -Ux FZF_TMUX_OPTS "-p 55%,60%"

Run man fzf-tmux to learn more about the available options.

If you want to customize the fzf popup border label, you can add T_FZF_BORDER_LABEL to your shell variable

# ~/.bashrc or ~/.zshrc
export T_FZF_BORDER_LABEL=' Your Custom Label '

or if you use fish:

# ~/.config/fish/config.fish
set -Ux T_FZF_BORDER_LABEL " Your Custom Label "

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

You can run a startup script when you create a new session. This is useful for running a command when you create a new session, like starting a dev server or automatically opening neovim to begin editing a file.

This works by adding a .t file to your desired directory. Here is a quick script for bootstrapping that file:

touch .t && chmod +x .t && echo -e '#!/usr/bin/env bash\n' > .t && nvim .t

I like opening Neovim and the find file Telescope prompt to quickly find a file to edit. Here is an example of what I put in many of my projects:

#!/usr/bin/env bash
nvim -c 'Telescope find_files'

So, when you open any project that detects a .t it will automatically run that script when a session is created.

This feature is in early development so please feel free to give feedback if you have ideas for how to improve on it.

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: K, mods: Command, chars: "\x02\x54" } # open t - tmux smart session manager

map cmd+k send_text all \x02\x54

{ key = 'j', mods = 'CMD', action = wezterm.action.SendString '\x02\x54' }, -- open t - tmux smart session manager

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.