https://github.com/Subbeh/tmux-tpad
Floating window manager for Tmux
https://github.com/Subbeh/tmux-tpad
Last synced: 22 days ago
JSON representation
Floating window manager for Tmux
- Host: GitHub
- URL: https://github.com/Subbeh/tmux-tpad
- Owner: Subbeh
- License: gpl-3.0
- Created: 2024-11-24T20:08:22.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-06T22:31:26.000Z (about 1 month ago)
- Last Synced: 2025-11-07T00:17:55.759Z (about 1 month ago)
- Language: Shell
- Size: 45.9 KB
- Stars: 17
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-tmux - tmux-tpad
README
# tmux-tpad
A lightweight floating window manager for tmux that allows you to create customizable popup sessions for different workflows.
## Features
- 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
## Installation
### Using TPM (recommended)
1. Install [Tmux Plugin Manager (TPM)](https://github.com/tmux-plugins/tpm) if you haven't already
2. Add the following to your `~/.tmux.conf`:
```tmux
set -g @plugin 'Subbeh/tmux-tpad'
```
3. Press `prefix` + I to install the plugin
## Configuration
TPad sessions are configured using tmux options in the format: `@tpad--`.
### Global Options
| Option | Default | Description |
| ----------- | ------- | ------------------------------------------- |
| @tpad-debug | false | Enable debug logging to `~/.cache/tpad.log` |
### Required Options
| Option | Description |
| ------ | ---------------------------------------------------------------- |
| bind | Key binding to toggle the popup session (e.g., "C-p" for Ctrl+P) |
### Appearance Options
| 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) |
### Behavior Options
| Option | Default | Description |
| ------- | ------- | ----------------------------------------------------- |
| dir | $HOME | Working directory for the session |
| cmd | | Command to execute when popup opens |
| prefix | | Custom tmux prefix for the session |
| env | | Additional environment variables |
| opts | | Session-specific tmux options (semicolon-separated) |
| per-dir | false | Create separate sessions per git repository/directory |
## Example Configuration
Here's a comprehensive example showing different use cases:
```tmux
# 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"
```
## Usage
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
Full-screen mode can be toggled by pressing the tmux prefix key with Ctrl+f from within a tpad session
### Per-Directory Sessions
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:**
```tmux
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.
### Session-specific Options
You can set session-specific tmux options using the `opts` configuration. Multiple options can be separated with semicolons:
```tmux
# 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"
```
## Roadmap
- [ ] Window controls (resize, maximize, minimize)
- [ ] Image support for terminals with kitty protocol
- [ ] Session persistence options
- [ ] Multiple popup layouts/splits
## Credits
This project was inspired by:
- [Dismissable Popup Shell in tmux](https://willhbr.net/2023/02/07/dismissable-popup-shell-in-tmux/)
- [omerxx/tmux-floax](https://github.com/omerxx/tmux-floax)
## License
MIT