https://github.com/gufranco/tmux-launcher-revamped
Launch any TUI app (lazygit, yazi, lf, k9s, htop) in a tmux popup or window from the current pane path. Configurable per app, popup gated to 3.2 with window fallback, 95%+ tested
https://github.com/gufranco/tmux-launcher-revamped
bash display-popup dotfiles launcher lazygit popup shell terminal tmux tmux-plugin tpm tui yazi
Last synced: 3 days ago
JSON representation
Launch any TUI app (lazygit, yazi, lf, k9s, htop) in a tmux popup or window from the current pane path. Configurable per app, popup gated to 3.2 with window fallback, 95%+ tested
- Host: GitHub
- URL: https://github.com/gufranco/tmux-launcher-revamped
- Owner: gufranco
- License: mit
- Created: 2026-06-21T15:38:29.000Z (5 days ago)
- Default Branch: main
- Last Pushed: 2026-06-22T23:07:35.000Z (4 days ago)
- Last Synced: 2026-06-23T01:06:41.935Z (4 days ago)
- Topics: bash, display-popup, dotfiles, launcher, lazygit, popup, shell, terminal, tmux, tmux-plugin, tpm, tui, yazi
- Language: Shell
- Size: 17.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
tmux-launcher-revamped
**Launch any TUI app in a popup or a window, scoped to the current pane's directory, with one configurable binding per app.**
[](https://github.com/gufranco/tmux-launcher-revamped/actions/workflows/tests.yml) [](LICENSE)
**any** app · **popup or window** · **tmux 1.9 to 3.5** · **41** tests · **95%+** coverage
Bind a key to open `lazygit`, `yazi`, `lf`, `htop`, `k9s`, or any other terminal app, in a floating popup or a fresh window, always starting in the current pane's directory. You list the apps and set a key, command, mode, and size for each. Popups need tmux 3.2, so on older tmux a popup launcher falls back to a window automatically.
Built from [tmux-plugin-template](https://github.com/gufranco/tmux-plugin-template).
Any app
Define `name`, key, command, and mode for each launcher; nothing is hardcoded.
Popup or window
Pick a floating popup or a real window per app. Apps that need image passthrough work in a window.
Current directory
Every launcher starts in `#{pane_current_path}`, so the app opens where you are.
Version-aware
`display-popup` is used on tmux 3.2 and up; below that, a popup launcher opens a window instead.
## How it works
List your apps in `@launcher_apps`. For each app ``, set its options. `lazygit` (popup, `C-g`) and `yazi` (window, `C-y`) ship as working defaults.
```tmux
set -g @plugin 'gufranco/tmux-launcher-revamped'
# add your own apps to the list
set -g @launcher_apps 'lazygit yazi lazydocker htop k9s'
set -g @launcher_lazydocker_key 'C-d'
set -g @launcher_htop_key 'C-t'
set -g @launcher_k9s_key 'C-s'
```
## Configuration
`@launcher_apps` is a space separated list of app ids. Each id reads the options below.
| Option | Default | Meaning |
|--------|---------|---------|
| `@launcher_apps` | `lazygit yazi` | the apps to bind |
| `@launcher__key` | built-in for `lazygit`/`yazi`, else required | the prefix key |
| `@launcher__command` | the id itself | the shell command to run |
| `@launcher__mode` | `popup` (`yazi` is `window`) | `popup` or `window` |
| `@launcher__name` | the id itself | window name, in `window` mode |
| `@launcher__width` | `80%` | popup width |
| `@launcher__height` | `80%` | popup height |
An app listed without a key and without a built-in default is skipped, so a typo never produces a broken binding.
## Examples
Popular apps people bind, with the mode that works best. File and media tools with image previews want `window` mode, since tmux popups have no passthrough ([tmux#4329](https://github.com/tmux/tmux/issues/4329)).
| App | Command | Suggested mode | Why |
|-----|---------|----------------|-----|
| lazygit | `lazygit` | popup | quick git, no previews |
| lazydocker | `lazydocker` | popup | container TUI |
| gitui | `gitui` | popup | git TUI |
| k9s | `k9s` | popup | kubernetes TUI |
| htop / btop | `htop` / `btop` | popup | process monitor |
| gh dash | `gh dash` | popup | GitHub dashboard |
| taskwarrior-tui | `taskwarrior-tui` | popup | tasks |
| yazi | `yazi` | window | image previews need passthrough |
| lf | `lf` | window | file manager, previews |
| ranger | `ranger` | window | file manager, previews |
| nnn | `nnn` | window | file manager |
| broot | `broot` | window | directory tree, opens files |
A full block adding several of these:
```tmux
set -g @launcher_apps 'lazygit lazydocker k9s htop yazi lf'
set -g @launcher_lazydocker_key 'C-d'
set -g @launcher_k9s_key 'C-s'
set -g @launcher_htop_key 'C-t'
set -g @launcher_lf_key 'C-f'
set -g @launcher_lf_mode 'window'
# a roomier lazygit popup
set -g @launcher_lazygit_width '90%'
set -g @launcher_lazygit_height '85%'
```
## Install
With [TPM](https://github.com/tmux-plugins/tpm), add to `~/.tmux.conf`:
```tmux
set -g @plugin 'gufranco/tmux-launcher-revamped'
```
Then press `prefix + I` to install. Out of the box, `prefix + C-g` opens lazygit and `prefix + C-y` opens yazi.
Manual install:
```bash
git clone https://github.com/gufranco/tmux-launcher-revamped ~/.tmux/plugins/tmux-launcher-revamped
run-shell ~/.tmux/plugins/tmux-launcher-revamped/launcher-revamped.tmux
```
## Compatibility
Works on every tmux version TPM supports, 1.9 and up, on Linux (x86_64 and arm64) and macOS (Intel and Apple Silicon). The `popup` mode uses `display-popup`, which is tmux 3.2 and up; on older tmux a popup launcher opens a window instead, so every binding still works. Each launcher runs whatever command you give it, so the app itself must be installed.
## Development
```bash
make test # bats suite
make lint # shellcheck
make coverage # kcov line coverage on Linux
```
The decision logic lives in [`src/lib/launcher/launcher.sh`](src/lib/launcher/launcher.sh) as pure, seam-backed helpers, and the applier in [`src/launcher.sh`](src/launcher.sh) runs under a dry-run mode so the full binding matrix is validated without a live tmux.
## License
[MIT](LICENSE), copyright Gustavo Franco.