https://github.com/2KAbhishek/tmux-tea
tmux sessions as easy as tea ☕🪟
https://github.com/2KAbhishek/tmux-tea
manager plugin session tmux utility
Last synced: 6 days ago
JSON representation
tmux sessions as easy as tea ☕🪟
- Host: GitHub
- URL: https://github.com/2KAbhishek/tmux-tea
- Owner: 2KAbhishek
- License: gpl-3.0
- Created: 2023-10-18T15:52:31.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-15T05:12:00.000Z (5 months ago)
- Last Synced: 2025-05-03T14:41:03.348Z (11 days ago)
- Topics: manager, plugin, session, tmux, utility
- Language: Shell
- Size: 262 KB
- Stars: 53
- Watchers: 2
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-tmux - tea
README
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
- Integrations with tmuxinator for session specific configs
- Integrations with fzf for fuzzy search
- Supports session previews
- Integrations with zoxide for directory based session creation
## Setup
### ⚡ Requirements
- tmux, fd, fzf, zoxide (required)
- tmuxinator (for session layouts)
- eza (for directory previews)
### 🚀 Installation
Add the following to your `~/.tmux.conf`
```bash
set -g @plugin '2kabhishek/tmux-tea'
```
```bash
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
There are two ways to open tea
- ` - t`, this can be configured with the `@tea-bind` option e.g: `set -g @tea-bind "t"`
- Ctrl+t alternate binding, this can be configured with the `@tea-alt-bind` option, set it to `"false"` to disable
#### Keybindings
- Ctrl+f - Directory mode
- Ctrl+j - Zoxide mode
- Ctrl+s - Session mode
- Ctrl+w - Window mode
- Ctrl+x - Kill mode
- Ctrl+t - Toggle tea
#### 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:
```tmux
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 `` binding outside tmux as well using this sni[[ed]]
```bash
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.
```tmux
# 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:
```tmux
set -g @tea-session-name "full-path"
```
#### preview position
You can set the **preview position** to "top","bottom","left", or "right", default is "top".
```tmux
set -g @tea-preview-position "bottom"
```
#### input position
You can set the **input position** to "default", "reverse" or "reverse-list", default is "reverse".
```tmux
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`.
```tmux
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".
```tmux
set -g @tea-max-depth "3"
```
## Behind The Code
### 🌈 Inspiration
tmux-tea was inspired by [t-smart-tmux-session-manager](https://github.com/joshmedeski/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](https://github.com/2kabhishek/dots2k) — Dev Environment
- [nvim2k](https://github.com/2kabhishek/nvim2k) — Personalized Editor
- [sway2k](https://github.com/2kabhishek/sway2k) — Desktop Environment
- [qute2k](https://github.com/2kabhishek/qute2k) — Personalized Browser
### 🔍 More Info
- [tmux-tilit](https://github.com/2kabhishek/tmux-tilit) — Turns tmux into a terminal window manager
- [tmux2k](https://github.com/2kabhishek/tmux2k) — Makes your tmux statusbar pretty!
⭐ hit the star button if you found this useful ⭐
Source
| Blog
| Twitter
| LinkedIn
| More Links
| Other Projects
