tmux-expose 0.1.0

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 a single prefix binding.

Install

From this repository:

cargo install --path .

Verify the install:

tmux-expose --version

Quickstart

Run the UI directly inside tmux:

tmux-expose

Or open it in a tmux popup:

tmux display-popup -w 95% -h 90% -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

Controls

Key	Action
`Arrow keys` / `hjkl`	Move selection
`Enter`	Switch to selected session
`q` / `Esc` / `Ctrl-C`	Quit without switching

tmux Plugin

Install with TPM:

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

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

The plugin binds prefix + E by default:

prefix + E

It opens:

tmux display-popup -w 95% -h 90% -E "tmux-expose"

Configuration

Customize the tmux plugin before the @plugin line:

set -g @tmux-expose-key 'E'
set -g @tmux-expose-width '95%'
set -g @tmux-expose-height '90%'
set -g @tmux-expose-command 'tmux-expose --columns 2'

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

Use a direct binding if you do not use TPM:

bind-key E display-popup -w 95% -h 90% -E "tmux-expose"

macOS Gesture Integration

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

tmux display-popup -w 95% -h 90% -E "tmux-expose"

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

Development

Before opening a PR, run:

cargo fmt --check
cargo test
cargo clippy --all-targets --all-features -- -D warnings