Architecture

This document outlines how tmux-thumbs interacts with Tmux and the OS to provide a seamless overlay experience. This is useful for contributors or those debugging complex issues.

The Swapper Logic

The core interaction mechanism is located in src/swapper.rs. Unlike simple CLI tools, tmux-thumbs must draw over existing content without destroying it.

The Lifecycle of a Pick

1. Capture: When you trigger the plugin, it runs tmux capture-pane. This grabs the text content of the active pane, respecting current scroll position and zoom state.

2. Generation: The captured text is piped into the thumbs Rust binary. The binary:

   • Parses the text against regex patterns (src/state.rs).
   • Assigns hints based on the selected alphabet (src/alphabets.rs).
   • Generates a formatted view with ANSI colors.

3. The "Swap": Instead of drawing directly to the active pane (which might mess up running applications), tmux-thumbs:

   • Creates a new background window/pane.
   • Runs the thumbs binary in that new pane to display the hints.
   • Swaps the active pane with this new "thumbs pane".
   • To the user, it looks like an overlay appeared instantly.

4. Selection: The user interacts with the thumbs binary running in the swapped pane. When a selection is made:

   • The selected text is written to a temporary file (/tmp/thumbs-last).
   • The binary signals completion.

5. Cleanup & Execution: The swapper detects the signal:

   • Swaps the original pane back into focus.
   • Destroys the temporary "thumbs pane".
   • Reads the selection from the temporary file.
   • Executes the user-defined command (e.g., tmux set-buffer) using the selected text.

OSC52 Support

If enabled, tmux-thumbs attempts to copy directly to the system clipboard using OSC52 escape sequences.

• Implementation: src/swapper.rs encodes the selection in Base64 and wraps it in the \x1b]52;... sequence.
• Tmux Passthrough: It wraps this further in \x1bPtmux;...\x1b\\ to ensure Tmux passes it to the host terminal.