flash.tmux

A small tmux plugin for jumping around copy-mode using labels, inspired by flash.nvim and leap.nvim.

It is intentionally small: one tmux entrypoint and one Python script using only the standard library. The current focus is only visible copy-mode navigation.

What it does

When you are in tmux copy-mode, flash.tmux lets you type a search string and then jump to a visible match by pressing its label.

Example flow:

1. Enter tmux copy-mode.
2. Press s.
3. Type part of the text you can see, for example foo.
4. Press the label shown on the match you want.
5. The cursor moves to that match.

Esc or Ctrl-C cancels without moving the cursor.

Setup

Using TPM (recommended)

Add this to your tmux.conf:

set -g @plugin 'leo0o7/flash.tmux'

Then reload and install with TPM's prefix + I binding.

Manual Installation

Clone the repo somewhere local and source flash.tmux from your tmux config:

source-file /path/to/flash.tmux/flash.tmux

Reload tmux config after changing it.

Configuration

The plugin already sets defaults, so configuration is optional.

Set options before sourcing the plugin, or before the TPM plugin line.

@flash-key controls the key used inside copy-mode. The default is s:

set -g @flash-key f

@flash-labels controls the label alphabet. Earlier characters are assigned first. The default is asdfghjklASDFHJKLqwertyuiopzxcvbnmQWERTYUIOPZXCVBNM:

set -g @flash-labels 'asdfjkl;'

Colors can be configured like this:

set -g @flash-label-bg "#eb6b64"
set -g @flash-label-fg "#1d1f21"
set -g @flash-match-fg "#ffd166"
set -g @flash-match-bg ""
set -g @flash-prompt-bg "#eb6b64"
set -g @flash-prompt-fg "#1d1f21"
set -g @flash-backdrop-style dim # or none

Example with TPM:

set -g @flash-key f
set -g @flash-labels 'asdfjkl;'
set -g @flash-label-bg "#eb6b64"

set -g @plugin 'leo0o7/flash.tmux'

How it works

The tmux entrypoint binds the configured copy-mode key in both copy-mode-vi and copy-mode to scripts/flash.py.

On activation, the script:

1. Checks that the pane is in copy-mode.
2. Captures the visible copy-mode viewport with tmux capture-pane -p -e.
3. Opens a borderless tmux popup over the target pane.
4. Draws the captured text with dimming, match highlighting, and labels.
5. Reads keys in raw mode while updating the query.
6. Moves the cursor with tmux copy-mode cursor commands.

Lowercase queries are matched case-insensitively. Queries containing uppercase letters are matched case-sensitively.

Labels that would continue the current search text are skipped. For example, if se matches sea, the label a is not used for that match because pressing a should be able to continue the query instead of selecting immediately.

Project layout

flash.tmux          tmux plugin entrypoint and copy-mode binding
scripts/flash.py    capture, overlay rendering, input loop, tmux cursor movement
tests/              stdlib unittest coverage for the Python behavior

Development

Run the tests with stdlib unittest:

python3 -m unittest discover -s tests

Check the Python script compiles:

python3 -m py_compile scripts/flash.py

Show CLI options:

python3 scripts/flash.py --help

Current limitations

• It only operates on the visible copy-mode viewport.
• It depends on tmux popup support.
• It is designed for jumping the cursor, not selecting or copying text directly.

References

Neovim plugins:

• flash.nvim
• leap.nvim

Similar tmux plugins:

• flash-copy.tmux
• easyjump.tmux
• tmux-easy-motion
• tmux-fastcopy
• tmux-jump