tsman

a feature-rich session manager for tmux

Contents

• Features
• Requirements
• Installation
• Usage
• Sessions
• Layouts
• Menu
• Shell completions
• Menu keybindings
• Configuration
• Config file
• Shell / tmux integration
• Notes

Features

• Quickly save/restore/delete/edit/reload tmux sessions.
• Work with layouts - reusable window/pane structure templates that can be applied to any working directory.
• Manage sessions and layouts from the interactive TUI menu:
• Use keybindings to trigger actions (Save/Open/Edit/Delete/Rename/Kill/Reload).
• Toggle between sessions and layouts list views.
• Create new sessions from layout templates directly in the menu.
• Fuzzy-find sessions and layouts (powered by fuzzy-matcher).
• View session/layout structure in the preview panel.
• Shell completions for bash, zsh, and fish.

Requirements

• tmux >= v3.2 (recommended for the display-popup feature).

Installation

cargo install tsman

Usage

Each subcommand has a short alias shown in parentheses.

Sessions

Save current session (s)

tsman save <session_name> # save with the specified name
tsman save                # save with the current session name

Open a session (o)

tsman open <session_name>

Edit a session config file (e)

Opens the config file in $EDITOR.

tsman edit <session_name> # edit the specified session
tsman edit                # edit the current session

Reload a session (r)

Kill the running session and recreate it from its saved config. The session must be both active and saved.

tsman reload <session_name>
tsman reload # reload the current session

Delete a session config file (d)

tsman delete <session_name>

Layouts

Layouts capture a session's window/pane structure without working directories, so you can reuse the same arrangement across different projects.

Save current session as a layout (layout s)

tsman layout save <layout_name> # save with the specified name
tsman layout save               # save with the current session name

Create a session from a layout (layout c)

All panes in the new session start in the given working directory.

tsman layout create <layout_name> <work_dir>               # session name defaults to layout name
tsman layout create <layout_name> <work_dir> <session_name> # use a custom session name

List saved layouts (layout ls)

tsman layout list

Edit a layout config file (layout e)

tsman layout edit <layout_name>

Delete a layout (layout d)

tsman layout delete <layout_name>

Menu (m)

Open the interactive TUI menu.

tsman menu
tsman menu --preview              # start with the preview pane on
tsman menu --ask-for-confirmation # prompt before deleting
tsman menu -p -a                  # shorthand for both flags

Shell completions (c)

tsman completions bash > ~/.local/share/bash-completion/completions/tsman
tsman completions zsh > ~/.zfunc/_tsman
tsman completions fish > ~/.config/fish/completions/tsman.fish

Menu keybindings

Navigation:

Session actions:

Layout actions (when in layouts view):

UI controls:

Workdir completion controls (in layout creation):

Confirmation popup:

Help popup:

Configuration

Config file

tsman reads ~/.config/tsman/config.toml on startup.

Run the init command to generate one interactively:

tsman init

All fields are optional - omit any section or key to use the default value.

[menu]
preview = false              # start menu with the preview pane on
ask_for_confirmation = false # prompt before deleting
show_key_presses = false     # show key press hints in the menu footer

[storage]
sessions_dir = "~/.config/.tsessions" # where session YAML files are stored
layouts_dir  = "~/.config/.tlayouts"  # where layout YAML files are stored

Precedence (highest to lowest): CLI flag > environment variable > config file > default.

Shell / tmux integration

You can add keybindings/aliases to your tmux/shell config for faster usage.

~/.tmux.conf:

# open menu in a tmux popup with preview pane and delete confirmation on
# note: requires tmux v3.2+
bind -r f display-popup -E -w 80% -h 80% "tsman menu -p -a"
bind -r C-s run-shell "tsman save"

~/.zshrc:

alias mux-fd="tsman menu -p -a"

Notes

• $EDITOR must be set to use the edit command.
• Session names must be 1-30 characters, alphanumeric plus - and _.
• Config files are stored as YAML - you can edit them manually for fine-grained control.

Contributing

• Please see CONTRIBUTING.md

Acknowledgements

• tmuxinator
• ThePrimeagen's tmux-sessionizer