tmux-tea

tmux sessions as easy as tea ☕🪟

tmux-tea in action

tmux-tea is a tmux session manager aimed at simplifying and speeding up how you interact with tmux sessions. It's a one key solution to all your tmux session needs.

✨ Features

• Fuzzy Search: Integrations with fzf for intuitive session selection
• Smart Session Management: Integrations with tmuxinator for session specific configs
• Session Previews: Visual previews of existing sessions and directory contents
• Zoxide Integration: Directory-based session creation with smart directory jumping
• Multiple Session Support: Open multiple sessions at once by passing multiple arguments

Setup

⚡ Requirements

• tmux, fd, fzf, zoxide (required)
• tmuxinator (for session layouts)
• eza (for directory previews)

🚀 Installation

Add the following to your ~/.tmux.conf

set -g @plugin '2kabhishek/tmux-tea'

cd ~/.tmux/plugins/tmux-tea # replace ~/.tmux/plugins with your plugin installation path
ln -sfnv $PWD/bin/tea.sh  ~/.local/bin/tea # Add tea to $PATH, make sure ~/.local/bin is in your $PATH

💻 Usage

Command Line Usage

# Get help
tea --help

# Interactive mode with fzf
tea

# Single session
tea ~/Projects/myapp

# Multiple sessions
tea work personal ~/Projects/app1 ~/Projects/app2

# Mix paths and zoxide queries
tea ~/code/frontend backend-service ~/docs

Tmux Key Bindings

• <prefix> + t - Open tea (configurable with @tea-bind)
• Ctrl+t - Alternate binding (configurable with @tea-alt-bind, set to "false" to disable)

Interactive Mode Keybindings

• Ctrl+f - Directory mode (find directories)
• Ctrl+j - Zoxide mode (recent directories)
• Ctrl+s - Session mode (existing sessions)
• Ctrl+w - Window mode (existing windows)
• Ctrl+x - Kill mode (delete sessions)
• Ctrl+t - Toggle tea / exit

⚙️ Configuration

All configuration options have sensible defaults and can be customized via tmux options.

tmuxinator integration

If you have a .tmuxinator.yml file in your directory, tea will use it for setting up your session.

If you have a tmuxinator config file in ~/.config/tmuxinator/ that has the same name as your tmux session directory then that will be used.

If none of these are present a tmux session is created from scratch.

default command

If there is no tmuxinator config present, you can set a default command to run in the session using:

set -g @tea-default-command "$EDITOR"

This will open every new session after the initial one with your "$EDITOR" command running.

zsh integration

If you use zsh you can add the <C-t> binding outside tmux as well using this sni[[ed]]

bindkey -s '^T' ' tea^M ^M'

show nth parts of the path

You can set tea-show-nth option to show parts of the path, default is to show the last two dirs.

# shows the second last (-2) and the last (-1) directories
set -g @tea-show-nth "-2,-1"
# if you want to show the last three directories
set -g @tea-show-nth "-3,-2,-1"

full session names

You can set the session name to be the full path you select instead of the directory using:

set -g @tea-session-name "full-path"

preview position

You can set the preview position to "top","bottom","left", or "right", default is "top".

set -g @tea-preview-position "bottom"

input position

You can set the input position to "default", "reverse" or "reverse-list", default is "reverse".

set -g @tea-layout "reverse"

default directory for find mode

Set the default directory used by the find mode, first fallback is $HOME/Projects, second fallback is $HOME.

set -g @tea-find-path "$HOME/Projects"
# You can also set it to the parent directory of PWD
set -g @tea-find-path "$PWD/.."

max depth for find mode

Set the max depth used by the find mode, default depth is "2".

set -g @tea-max-depth "3"

Behind The Code

🌈 Inspiration

tmux-tea was inspired by t-smart-tmux-session-manager and shares a lot of code.

I wanted to add some more features that diverged from the original repo and wanted to keep the configs simpler.

💡 Challenges/Learnings

• Figuring out the preview script was quite tricky.
• Bash shenanigans!

🧰 Tooling

• dots2k — Dev Environment
• nvim2k — Personalized Editor
• sway2k — Desktop Environment
• qute2k — Personalized Browser

🔍 More Info

• tmux-tilit — Turns tmux into a terminal window manager
• tmux2k — Makes your tmux statusbar pretty!

---

⭐ hit the star button if you found this useful ⭐

Source | Blog | Twitter | LinkedIn | More Links | Other Projects