A tmux plugin inspired by flash.nvim that enables you to search visible words in the current tmux pane, then copy that word to the system clipboard by pressing the associated label key.
- Dynamic Search: Type to filter words in real-time as you search.
- Overlay Labels: Single key selection with labels overlayed on matches in the pane.
- Dimmed Display: Non-matching content is dimmed for visual focus.
- Clipboard Copy: Selected text is immediately copied to the system clipboard.
- Auto-paste Modifier: Use semicolon key as a modifier to automatically paste selected text.
- Configurable Word Boundaries: Honours tmux's
word-separatorsby default, with override support.
- Requirements
- Installation
- Usage
- Customisation
- ANSI colour codes
- Clipboard Implementation
- Debugging
- Development & Testing
- Future enhancements
- Demonstration
- Contributing
- Inspiration
- Other plugins
-
Install TPM (Tmux Plugin Manager).
-
Add
tmux-flash-copyto your~/.tmux.conf:set -g @plugin 'kristijan/flash-copy.tmux'
-
Start tmux and install the plugin.
Press
<tmux_prefix> + I(capital i, as in Install) to install the plugin.Press
<tmux_prefix> + U(capital u, as in Update) to update the plugin.
-
Clone this repository to your desired location:
git clone https://github.com/kristijan/flash-copy.tmux.git ~/.tmux/plugins/flash-copy.tmux -
Add the following to your
~/.tmux.conf:run-shell ~/.tmux/plugins/flash-copy.tmux/tmux-flash-copy.tmuxAny customisation variables should be set BEFORE the
run-shellline so they're correctly sourced.For example:
set -g @flash-copy-bind-key "f" set -g @flash-copy-prompt-indicator "❯" run-shell ~/.tmux/plugins/flash-copy.tmux/tmux-flash-copy.tmux
-
Reload your tmux configuration:
tmux source-file ~/.tmux.conf
- Press the bind key (default:
<tmux_prefix> S-f(that's<tmux_prefix> Shift+f)) to activate the search. - Type to search for words in the pane. The search is dynamic and updates as you type.
- Matching words will be highlighted in yellow with single-character labels in green.
- Press the label key corresponding to the word you want to copy.
- The selected text is immediately copied to your clipboard, and you are returned to your pane.
Tip
You can auto-paste your selected match by using the ; (semicolon) modifier key.
See the Auto-paste text section for more details.
| Keybinding | Action |
|---|---|
Ctrl+U |
Clear the entire search query |
Ctrl+W |
Clear the previous word |
Enter |
Copy the first match (determined by @flash-copy-reverse-search setting) |
;+<label> |
Copy and auto-paste the word (if auto-paste enabled) |
Ctrl+C / ESC |
Cancel and close the popup without copying |
By default, selecting a label will copy the text to the clipboard only. If auto-paste is enabled (the default), you can also paste the text automatically:
- Hold
;(semicolon) (orShift+;(colon) for uppercase labels) to activate the auto-paste modifier - Then press the label key to paste a specific word, or
Enterto paste the first match
The selected text will be copied to the clipboard AND automatically pasted into your pane.
The following configuration options are supported. Default values are listed, with overrides to be added to your tmux configuration (~/.tmux.conf).
| Option | Description |
|---|---|
@flash-copy-bind-key |
Key binding to activate tmux-flash-copy |
@flash-copy-word-separators |
Characters that define word boundaries |
@flash-copy-case-sensitive |
Case-sensitive searching |
@flash-copy-reverse-search |
Direction of label assignment when searching |
@flash-copy-auto-paste |
Enable auto-paste modifier functionality |
@flash-copy-debug |
Enable debug logging |
| Option | Description |
|---|---|
@flash-copy-prompt-position |
Controls where the prompt is positioned in the pane window |
@flash-copy-prompt-indicator |
Customises the prompt indicator |
@flash-copy-prompt-colour |
Customises the prompt indicator colour |
@flash-copy-prompt-placeholder-text |
Customises prompt placeholder text |
@flash-copy-idle-timeout |
Idle timeout in seconds before auto-exit |
@flash-copy-idle-warning |
Seconds before timeout to show warning in prompt |
| Option | Description |
|---|---|
@flash-copy-label-characters |
Customise the characters that can be used as labels |
@flash-copy-highlight-colour |
Customises the colour used to highlight the matched portion of text in search results |
@flash-copy-label-colour |
Customises the colour used for match labels |
Customise the key binding to activate tmux-flash-copy.
The default binding is S-f (Shift+F), which when combined with your tmux prefix becomes <prefix> S-f.
# Change the key binding to Ctrl+F
set -g @flash-copy-bind-key "C-f"
# Or use Alt+F
set -g @flash-copy-bind-key "M-f"Customise the characters that define word boundaries.
Priority order.
- First: Check @flash-copy-word-separators (custom user override)
- Fallback: Read tmux's built-in word-separators window option (can be overridden in
~/.tmux.conf)
This allows you to control what constitutes a "word" for the plugin. This is particularly useful when working with configuration strings like #{@variable_name} where you want @ and } to be word boundaries.
# Use custom word separators (overrides tmux's word-separators)
set -g @flash-copy-word-separators ' ()":,;<>~!@#$%^&*|+=[]{}?`'
# To add single quote to the separators
set -ag @flash-copy-word-separators "'"Controls whether search is case-sensitive or case-insensitive.
onortrue: Search is case-sensitive (e.g.,Testwill not matchtest)offorfalse: Search is case-insensitive, ignoring case differences (default behaviour)
# Enable case-sensitive search
set -g @flash-copy-case-sensitive "on"Controls the direction of label assignment when searching:
onortrue: Labels are assigned from bottom to topofforfalse: Labels are assigned from top to bottom
Setting to off is useful if you have your @flash-copy-prompt-position at the top of the screen. This means matches are assigned closer to your prompt.
# Switch to top-to-bottom search
set -g @flash-copy-reverse-search "off"Controls whether the auto-paste modifier (semicolon and colon keys) is enabled.
onortrue: Auto-paste modifier is enabled (default). Pressing;(semicolon) or:(colon) activates the auto-paste mode, allowing you to copy and automatically paste selected text.offorfalse: Auto-paste modifier is disabled. The;(semicolon) and:(colon) keys work as regular characters in search queries instead of being reserved for the modifier.
# Disable auto-paste modifier (semicolon and colon work in searches)
set -g @flash-copy-auto-paste "off"Controls where the prompt is positioned in the pane window.
bottom: Prompt is displayed at the bottom (default)top: Prompt is displayed at the top
This is independent of the @flash-copy-reverse-search setting, allowing you to combine any desired configuration.
# Place prompt at the top of the popup
set -g @flash-copy-prompt-position "top"Customises the prompt indicator or string displayed before the search input.
- Default: A single
>character - Can be set to any string (e.g.,
>>>,❯,$,λ)
# Use a different prompt character
set -g @flash-copy-prompt-indicator "❯"
# Use multiple characters as prompt
set -g @flash-copy-prompt-indicator ">>>"Customises the ANSI colour code applied to the prompt indicator. This allows you to style the prompt with different colours and formatting (bold, dim, etc.).
- Default:
\033[1m(bold) - Accepts any valid ANSI colour code (see ANSI colour codes section below)
- The colour applies only to the prompt indicator, not the search input
# Use bold red for the prompt
set -g @flash-copy-prompt-colour "\033[1;31m"
# Use bold cyan for the prompt
set -g @flash-copy-prompt-colour "\033[1;36m"
# Use non-bold yellow for the prompt
set -g @flash-copy-prompt-colour "\033[0;33m"Customises the ghost text that appears in the prompt input when it's empty.
- If set to any string: Shows that string as dimmed placeholder text
- If set to empty string (
""): Disables placeholder text entirely
The placeholder text automatically disappears when you start typing.
# Use custom placeholder
set -g @flash-copy-prompt-placeholder-text "Type to search..."
# Disable placeholder text
set -g @flash-copy-prompt-placeholder-text ""Controls the idle timeout in seconds before the popup automatically exits.
- Default:
15seconds - Minimum:
1second (values less than 1 are ignored) - Set to a higher value if you need more time to make your selection
When no user input is detected for the specified duration, tmux-flash-copy will automatically exit to prevent indefinitely blocking the terminal.
# Extend idle timeout to 30 seconds
set -g @flash-copy-idle-timeout "30"Controls when the idle timeout warning appears, specified as seconds BEFORE the timeout.
- Default:
5seconds (warning appears 5 seconds before timeout) - Must be less than
@flash-copy-idle-timeoutfor a warning to appear - If set equal to or greater than
@flash-copy-idle-timeout, no warning will be displayed
# Show warning 10 seconds before timeout (at 20s if timeout=30s)
set -g @flash-copy-idle-timeout "30"
set -g @flash-copy-idle-warning "10"
# Show warning very late, only 2 seconds before timeout
set -g @flash-copy-idle-warning "2"
# Disable warning by setting equal to timeout
set -g @flash-copy-idle-timeout "15"
set -g @flash-copy-idle-warning "15" # No warning will appearNote: Any keypress resets the idle timer back to zero, so actively searching or typing will prevent timeout.
Customises the ordered list of characters used as match labels. Provide a string of characters in the order you want them to be assigned. If left unset the plugin uses the default label set inspired by flash.nvim.
Labels are guaranteed not to exist as a continuation of the search pattern.
Examples:
# Use only lower-case letters as labels
set -g @flash-copy-label-characters "asdfghjklqwertyuiopzxcvbnm"
# Custom order: prioritise hjkl then asdf
set -g @flash-copy-label-characters "hjklasdf..."Customises the ANSI colour code used to highlight the matched portion of text in search results.
- Default:
\033[1;33m(bold yellow) - Accepts any valid ANSI colour code (see ANSI colour codes section below)
# Use bold red for highlighting
set -g @flash-copy-highlight-colour "\033[1;31m"Customises the ANSI colour code used for match labels (the keyboard shortcut indicator).
- Default:
\033[1;32m(bold green) - Accepts any valid ANSI colour code (see ANSI colour codes section below)
# Use bold cyan for labels
set -g @flash-copy-label-colour "\033[1;36m"Common ANSI colour codes.
\033[1;31m- Bold red\033[1;32m- Bold green\033[1;33m- Bold yellow\033[1;34m- Bold blue\033[1;35m- Bold magenta\033[1;36m- Bold cyan\033[1;37m- Bold white\033[0;31m- Red (non-bold)\033[0;32m- Green (non-bold)
For information on clipboard methods, troubleshooting, and platform-specific recommendations, see CLIPBOARD.md.
For information on debugging information, including log format, troubleshooting specific issues, and example debug sessions, see DEBUGGING.md.
For information on setting up a development environment, running tests, and code quality checks, see TESTING.md.
- I'm manually parsing the output of
tmuxcommands using a subprocess. This should ideally be using something like libtmux. I might consider switching to this in a major revision update, as I'm likely leaving increased performance on the table. - Initially I tried getting this to work using the terminal alternate screen functionality, but couldn't come to a solution that didn't involve using
send-keysto enable alternate screen. Using an alternate screen could potentially simplify the popup placement logic.
The following configuration is used in the demonstration GIF.
set -g @plugin 'kristijan/flash-copy.tmux'
set -g @flash-copy-prompt-indicator "❯"
set -g @flash-copy-prompt-colour "\033[38;2;203;166;247m"- Font is MonaspiceAr Nerd Font Mono
- Shell prompt is starship
- Catppuccin Mocha theme is used for both tmux and bat.
Contributions are welcome! Please feel free to submit issues or pull requests.
Before submitting a PR:
- Run tests and code quality checks (see TESTING.md).
- Ensure all tests pass.
- Add tests for new functionality.
- Update documentation as needed.
This plugin is inspired by the excellent flash.nvim plugin for Neovim, adapted for the tmux ecosystem.
Check out my other plugin TMUX FZF Pane Switch, that allows you to switch to any pane, in any session, by searching and filtering using fzf.