Tmux Popups

Use tmux display-popup for floating windows - quick terminals, music players, AI assistants, and more.

cli

Tmux 3.2+ introduced display-popup, a command for creating floating overlay windows. Popups appear centered by default and are ideal for quick tasks without disrupting your current layout - run a command, check status, or interact with a tool, then dismiss it.

Basic Syntax

tmux display-popup [options] [command]

Common Flags

FlagDescription
-EClose popup when command exits
-w <width>Width (percentage like 80% or columns)
-h <height>Height (percentage or rows)
-x <position>Horizontal position
-y <position>Vertical position
-d <path>Start directory for the command
-T <title>Popup title (appears in border)

Examples

# Run htop in a centered 80% popup
tmux display-popup -E -w 80% -h 80% "htop"

# Quick git status popup
tmux display-popup -E "git status"

# Popup with title
tmux display-popup -E -T "System Monitor" "htop"

Personal Configurations

Music Player Popup

From ~/.config/tmux/tmux.conf:

# Launch rmpc music player in popup
bind-key t display-popup -E -w 90% -h 90% "rmpc"

Press prefix + t to open the rmpc MPD client in a large popup. The -E flag means it closes when you quit rmpc.

Claude Code Popup

From the app-mgmt project, Claude Code runs in a tmux popup for interactive AI-assisted tasks:

tmux_cmd = f'tmux display-popup -E -w 70% "bash {script_file}"'

This creates a focused 70% width popup for Claude sessions, keeping the main terminal visible for context.

Creative Uses

Toggle-able Popup Shell

Create a persistent popup session that can be quickly shown/hidden - perfect for running quick commands without opening splits:

bind-key g if-shell -F '#{==:#{session_name},popup}' {
    detach-client
} {
    display-popup -E -w 80% -h 80% "tmux new-session -A -s popup"
}

This creates a “popup” session that persists between invocations. Press the binding again to dismiss it.

Directory-Based Sessions

Open a popup session named after the current directory:

bind-key C-g display-popup -E -w 80% -h 80% \
    "tmux new-session -A -s $(basename #{pane_current_path})"

Fuzzy Finder Integration

Run fzf in a popup for file selection:

bind-key f display-popup -E -w 60% -h 60% \
    "fzf --preview 'cat {}' | xargs -r nvim"

Quick Utilities

# Lazygit popup
bind-key G display-popup -E -w 90% -h 90% "lazygit"

# Process viewer
bind-key H display-popup -E -w 80% -h 80% "htop"

# Note-taking popup
bind-key n display-popup -E -w 60% -h 60% "nvim ~/notes/scratch.md"

Custom Menus with display-menu

Create interactive menus for common operations:

bind-key m display-menu -T "Session Menu" \
    "New Session" n "new-session" \
    "Kill Session" k "kill-session" \
    "Rename" r "command-prompt -I '#S' 'rename-session \"%%\"'"

Help/Cheatsheet Popup

Replace the default ? binding with a custom help popup:

bind-key ? display-popup -E -w 80% -h 80% \
    "cat ~/.config/tmux/cheatsheet.md | less"

Tips

  1. Use -E for commands that should close the popup on exit
  2. Percentage sizes (-w 80%) adapt to terminal size
  3. Combine with tmux new-session -A -s <name> for persistent popup sessions
  4. Escape closes popups by default
  5. Popups can run any shell command or start nested tmux sessions

Resources

-
-