tmux-expose 0.5.3

Why tmux.expose

Switching tmux sessions with a list works, but it gives you names instead of context. tmux.expose shows every session as a live text thumbnail so you can jump to the right workspace visually.

• See before switching. Browse sessions in a responsive grid with live pane previews.
• Terminal-native. A small Rust TUI that runs inside your terminal or a tmux popup.
• Color-aware previews. tmux ANSI colors are preserved in thumbnails.
• Fast keyboard flow. Move with arrows or hjkl, switch with Enter, leave with q or Esc.
• TPM-ready. Install it as a tmux plugin and launch with Alt+e.

Install

The shortest path is crates.io:

cargo install tmux-expose

tmux Plugin

Install with TPM:

set -g @plugin 'cesarferreira/tmux.expose'

Reload tmux config, then press prefix + I to install plugins.

The plugin binds Alt+e by default:

Alt+e

It opens:

tmux display-popup -w 100% -h 100% -E "tmux-expose"

With the default binding, press Alt+e again while tmux.expose is open to close it without switching.

Configuration

Customize the tmux plugin before the @plugin line:

set -g @tmux-expose-key 'E'
set -g @tmux-expose-key-table 'prefix'
set -g @tmux-expose-width '100%'
set -g @tmux-expose-height '100%'
set -g @tmux-expose-anchor 'center'
set -g @tmux-expose-style 'bg=colour234'
set -g @tmux-expose-border-style 'fg=colour245'
set -g @tmux-expose-selected-color 'yellow'
set -g @tmux-expose-attached-color 'green'
set -g @tmux-expose-inactive-color 'white'
set -g @tmux-expose-command 'tmux-expose --columns 2'

set -g @plugin 'cesarferreira/tmux.expose'

@tmux-expose-anchor accepts center, top, bottom, left, or right. For example, use set -g @tmux-expose-anchor 'bottom' with set -g @tmux-expose-height '50%' to show tmux.expose in the bottom half of the screen.

@tmux-expose-style maps to display-popup -s, and @tmux-expose-border-style maps to display-popup -S.

Card colors

Each session card is highlighted based on its state. Recolor any of them to match your theme:

Values accept a color name (yellow, cyan, …), a 256-color index (colour208 or 208), or a hex value (#ff8700). Omit an option to keep its default.

For example, a Dracula-flavored setup:

set -g @tmux-expose-selected-color '#bd93f9'
set -g @tmux-expose-attached-color '#50fa7b'
set -g @tmux-expose-inactive-color '#6272a4'

The same colors are also available as CLI flags when running the binary directly:

tmux-expose --selected-color '#bd93f9' --attached-color '#50fa7b' --inactive-color '#6272a4'

Custom Example

This configuration binds tmux.expose to prefix + s and opens it as a bottom-anchored popup using 60% of the screen height:

set -g @tmux-expose-key 's'
set -g @tmux-expose-key-table 'prefix'
set -g @tmux-expose-width '100%'
set -g @tmux-expose-height '60%'
set -g @tmux-expose-anchor 'bottom'
set -g @tmux-expose-style 'bg=colour234'
set -g @tmux-expose-border-style 'fg=colour245'

set -g @plugin 'cesarferreira/tmux.expose'

It produces a popup equivalent to:

tmux display-popup -w 100% -h 60% -y '#{popup_pane_bottom}' -s 'bg=colour234' -S 'fg=colour245' -e TMUX_EXPOSE_TOGGLE_KEY=s -E "tmux-expose"

Use a direct binding if you do not use TPM:

bind-key -T root M-e display-popup -w 100% -h 100% -e TMUX_EXPOSE_TOGGLE_KEY=M-e -E "tmux-expose"

Quickstart

Run the UI directly inside tmux:

tmux-expose

Or open it in a tmux popup:

tmux display-popup -w 100% -h 100% -E "tmux-expose"

By default, thumbnails are sized into a balanced grid that fits all sessions on screen. Override the layout when you want larger previews or a fixed grid:

tmux-expose --thumbnail-width 48
tmux-expose --columns 2
tmux-expose --thumbnail-width 48 --columns 2

Refresh interval defaults to 500ms:

tmux-expose --refresh-interval 500

Recolor the card highlights (names, 256-color indices, or hex values are accepted):

tmux-expose --selected-color cyan --attached-color green --inactive-color white

Controls

macOS Gesture Integration

Use BetterTouchTool, Hammerspoon, Raycast, or another automation tool to trigger:

tmux display-popup -w 100% -h 100% -E "tmux-expose"

The app itself is terminal-only and does not depend on macOS-specific APIs.

Development

Before opening a PR, run:

make check

License

MIT © Cesar Ferreira