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

1. Install Tmux Plugin Manager (TPM) if you haven't already
2. Add the following to your ~/.tmux.conf:

   set -g @plugin 'Subbeh/tmux-tpad'

3. Press prefix + I to install the plugin

TPad sessions are configured using tmux options in the format: @tpad-<session_name>-<option>.

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           "lazygit"
set -g @tpad-git-per-dir       "true"
set -g @tpad-git-style         "fg=yellow"
# 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%"
# 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"

1. Configure your popup sessions in tmux.conf as shown above
2. Press your tmux prefix key (default: Ctrl+b)
3. Press the configured key binding to toggle the popup (e.g., Ctrl+g for the git session)
4. 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

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"

• Window controls (resize, maximize, minimize)
• Image support for terminals with kitty protocol
• Session persistence options
• Multiple popup layouts/splits

This project was inspired by:

• Dismissable Popup Shell in tmux
• omerxx/tmux-floax

MIT