tmux-sessionizer

tmux-sessionizer (tms)

The fastest way to manage projects as tmux sessions

What is tmux-sessionizer?

Tmux Sessionizer is a tmux session manager that is based on ThePrimeagen's tmux-sessionizer but is opinionated and personalized to my specific tmux workflow. And it's awesome. Git worktrees are automatically opened as new windows, specific directories can be excluded, a default session can be set, killing a session jumps you to a default, and it is a goal to handle more edge case scenarios.

Tmux has keybindings built-in to allow you to switch between sessions. By default, these are leader-( and leader-)

Switching between windows is done by default with leader-p and leader-n

Usage

The tms command

Running tms will find the repos and fuzzy find on them. It is very convenient to bind the tms command to a tmux keybinding so that you don't have to leave your text editor to open a new project. I have this tmux binding bind C-o display-popup -E "tms". See the image below for what this look like with the tms switch keybinding

The tms switch command

There is also the tms switch command that will show other active sessions with a fuzzy finder and a preview window. This can be very useful when used with the tmux display-popup which can open a popup window above the current session. That popup window with a command can have a keybinding. The config could look like this bind C-j display-popup -E "tms switch". Then when using leader+C-j the popup is displayed (and it's fast)

The tms windows command

Similar to tms switch, you can show other active windows in the current session with a fuzzy finder and a preview window. A config for use with display-popup, could look like this bind C-w display-popup -E "tms windows".

The tms rename command

Using this command you can automatically rename the active session along with the directory name and the active directory inside all the panes in the active session will be changed to the renamed directory

tms rename

bind C-w command-prompt -p "Rename active session to: " "run-shell 'tms rename %1'".

The tms refresh command

Using this command you can automatically generate missing worktree windows for the active session or a provided session_name.

tms refresh

bind C-r "run-shell 'tms refresh'".

The tms kill command

Using this command you can kill current tmux session and automatically jump to another. The config could look like this bind C-k confirm -p "Kill current session? (y/N):" "run-shell 'tms kill'". Then when using leader+C-k you have to confirm killing of the current session with y. Any other input or just pressing enter aborts it.

With tms config --session you can define to which session you will switch to after the kill.

CLI overview

Use tms --help

…

Configuring defaults

…

Config file location

By default, tms looks for a configuration in the platform-specific config directory:

Linux: /home/alice/.config/tms/config.toml
macOS: /Users/Alice/Library/Application Support/tms/config.toml
Windows: C:\Users\Alice\AppData\Roaming\tms\config.toml

If the config directory can't be found, it will also check ~/.config/tms/config.toml (only relevant on Windows and macOS). Alternatively, you can specify a custom config location by setting the TMS_CONFIG_FILE environment variable in your shell profile with your desired config path.

Customizing keyboard shortcuts

Keyboard shortcuts can be customized by adding a [shortcuts] section in the config file and adding bindings as pairs of shortcut = action, for example:

[shortcuts]
"ctrl-k" = "delete_to_line_end"

Available actions are:

• "" (to remove a default binding)
• "cancel"
• "confirm"
• "backspace"
• "delete"
• "move_up"
• "move_down"
• "cursor_left"
• "cursor_right"
• "delete_word"
• "delete_to_line_start"
• "delete_to_line_end"
• "move_to_line_start"
• "move_to_line_end"

Installation

Pre-built binaries

Check the releases page for the latest pre-built binaries

Cargo

Install with cargo install tmux-sessionizer or

From source

Clone the repository and install using cargo install --path . --force

Usage Notes

The 'tms sessions' command can be used to get a styled output of the active sessions with an asterisk on the current session. The configuration would look something like this

set -g status-right " #(tms sessions)"

E.g. If this configuration is used it can be helpful to rebind the default tmux keys for switching sessions so that the status bar is refreshed on every session switch. This can be configured with settings like this.

bind -r '(' switch-client -p\; refresh-client -S
bind -r ')' switch-client -n\; refresh-client -S

Shell completions

Bash

echo "source > ~/.bashrc

Zsh

echo "source > ~/.zshrc

Fish

echo "COMPLETE=fish tms | source" >> ~/.config/fish/config.fish