A lightweight floating window manager for tmux that allows you to create customizable popup sessions for different workflows.
- Create multiple named popup sessions with different configurations
- Customize appearance, size, and position of each popup
- Run specific commands automatically when opening a popup
- Set custom working directories per popup
- Support for custom key bindings and tmux prefix keys
- Per-directory sessions: create separate sessions for each git repository
- Eject a pane from the popup into the parent session, and reclaim it back
- Install Tmux Plugin Manager (TPM) if you haven't already
- Add the following to your
~/.tmux.conf:set -g @plugin 'Subbeh/tmux-tpad'
- Press
prefix+ I to install the plugin
TPad sessions are configured using tmux options in the format: @tpad-<session_name>-<option>.
| Option | Default | Description |
|---|---|---|
| @tpad-debug | false | Enable debug logging to ~/.cache/tpad.log |
| @tpad-bind-fullscreen | C-f | Key to toggle fullscreen mode (prefix + key) |
| @tpad-bind-eject | C-e | Key to eject a pane from the popup (prefix + key) |
| Option | Description |
|---|---|
| bind | Key binding to toggle the popup session (e.g., "C-p" for Ctrl+P) |
| Option | Default | Description |
|---|---|---|
| title | #[fg=magenta,bold] TPad: @instance@ |
Popup window title |
| width | 60% | Popup width (percentage or columns) |
| height | 60% | Popup height (percentage or rows) |
| style | fg=blue | Popup window style |
| border_style | Border style (e.g., "fg=cyan") | |
| border_lines | rounded | Border line style (rounded/none/etc) |
| pos_x | Horizontal position (percentage, pixels, or left/center/right) | |
| pos_y | Vertical position (percentage, pixels, or top/center/bottom) |
Here's a comprehensive example showing different use cases:
# Simple scratchpad
set -g @tpad-scratchpad-bind "C-p"
set -g @tpad-scratchpad-opts "status on"
set -g @tpad-scratchpad-dir "#{pane_current_path}"
# Git management with lazygit (separate session per git repo)
set -g @tpad-git-bind "C-g"
set -g @tpad-git-cmd "git rev-parse --is-inside-work-tree && lazygit"
set -g @tpad-git-per-dir "true"
set -g @tpad-git-style "fg=red"
# Claude sessions (separate session per git repo)
set -g @tpad-claude-bind "C-c"
set -g @tpad-claude-height "90%"
set -g @tpad-claude-width "30%"
set -g @tpad-claude-pos_x "350%"
set -g @tpad-claude-pos_y "80%"
set -g @tpad-claude-per-dir "true"
set -g @tpad-claude-cmd "claude-runner"
set -g @tpad-claude-opts "status on"
set -g @tpad-claude-eject-split "right"
set -g @tpad-claude-eject-size "40"
# Notes with Neovim
set -g @tpad-notes-bind "C-n"
set -g @tpad-notes-dir "${NOTES_DIR}"
set -g @tpad-notes-cmd "nvim -c NvimTreeOpen"
set -g @tpad-notes-prefix "None"
set -g @tpad-notes-width "80%"
set -g @tpad-notes-height "80%"
# K9s
set -g @tpad-k9s-bind "C-k"
set -g @tpad-k9s-style "fg=blue"
set -g @tpad-k9s-height "80%"
set -g @tpad-k9s-width "80%"
set -g @tpad-k9s-cmd "k9s"
# Task management
set -g @tpad-tasks-bind "C-t"
set -g @tpad-tasks-style "fg=green"
set -g @tpad-tasks-height "40%"
set -g @tpad-tasks-width "40%"
set -g @tpad-tasks-pos_x "right"
set -g @tpad-tasks-pos_y "bottom"
set -g @tpad-tasks-cmd "taskwarrior-tui"
# Right-click to open a scratchpad (table auto-detected as root for mouse events)
set -g @tpad-scratch-bind "MouseDown3Pane"
# Keyboard shortcut without prefix key (explicit root table)
set -g @tpad-quick-bind "C-Space"
set -g @tpad-quick-table "root"- Configure your popup sessions in
tmux.confas shown above - Press your tmux prefix key (default: Ctrl+b), then press the configured key binding to toggle the popup (e.g., Ctrl+g for the git session)
- For root-table bindings (
table "root"or mouse events), no prefix key is needed - The popup will close automatically when the command exits
Full-screen mode can be toggled by pressing the tmux prefix key with Ctrl+f from within a tpad session (configurable via @tpad-bind-fullscreen).
A pane can be ejected from the popup into the parent session by pressing prefix+Ctrl+e from within a tpad session (configurable via @tpad-bind-eject). The popup closes and the pane is moved into the parent session as a split, with position and size controlled by eject-split and eject-size.
To reclaim the pane back into the popup, simply toggle the popup again with its normal key binding. If the ejected pane still exists it will be moved back into the tpad session (as a new window if the session has other windows); otherwise a fresh session is created as usual.
# Eject to the right at 40% width, reclaim with C-c
set -g @tpad-claude-bind "C-c"
set -g @tpad-claude-eject-split "right"
set -g @tpad-claude-eject-size "40"When per-dir is enabled, tmux-tpad creates separate sessions for each git repository or directory. This is particularly useful for tools like lazygit, where you want independent sessions for different projects.
How it works:
- Detects the git root of your current pane's directory
- Creates a unique session per git root (e.g.,
tpad_git_project1,tpad_git_project2) - Automatically sets the working directory to the git root
- Falls back to the current directory if not in a git repository
Example:
set -g @tpad-git-bind "C-g"
set -g @tpad-git-cmd "lazygit"
set -g @tpad-git-per-dir "true"Now pressing Ctrl-g in different git repositories will open separate lazygit sessions for each project.
You can set session-specific tmux options using the opts configuration. Multiple options can be separated with semicolons:
# Enable the statusline for a specific popup
set -g @tpad-scratchpad-opts "status on"
# Multiple options
set -g @tpad-scratchpad-opts "status on; status-position top"This project was inspired by:
MIT