🐇 tmux-jump
Incremental-narrowing jump for tmux — type what you see, land on it.
Like flash.nvim / leap.nvim, but for the visible tmux pane. Press a key, start typing the word you're looking at, and the moment only one match remains the copy-mode cursor jumps there. No hints, no labels, no two-char mnemonics to memorise.
✨ Features
- 🎯 Incremental narrow — type and watch matches shrink, auto-jump on unique match
- 🔍 Smart-case — uppercase in query ⇒ case-sensitive, otherwise insensitive
- 🖼️ In-place overlay — pane-sized borderless popup dims non-matches and highlights the rest
- 🪶 Single static binary — Go, no runtime deps on the user's box
- 🔒 Fails safe — any error path yields control back cleanly, never leaves the pane stuck
- 🧵 Visible pane only — scoped to what's on screen, nothing funny with scrollback
📦 Install
With TPM
set -g @plugin 'j4hangir/tmux-jump'
Then prefix + I to fetch & install.
Manual
git clone https://git.j4hangir.com/tmux/tmux-jump ~/.tmux/plugins/tmux-jump echo "run-shell ~/.tmux/plugins/tmux-jump/tmux-jump.tmux" >> ~/.tmux.conf tmux source-file ~/.tmux.conf
On first launch a wizard prompts you to either download the prebuilt Linux x86_64 binary (from GitLab CI) or build from source with Go.
🗑️ Uninstall
tmux unbind j # or whatever @jump-key you chose rm -rf ~/.tmux/plugins/tmux-jump # also removes bin/tmux-jump sed -i.bak '/tmux-jump\|@jump-/d' ~/.tmux.conf tmux source ~/.tmux.conf
🕹️ Usage
Press prefix + j (default), start typing. That's it.
| Key | Action |
|---|---|
| any printable char | append to query, re-narrow |
Backspace | pop last char |
Enter | jump to selected match |
Tab | (≤10 matches) enter hint mode — overlay hint chars on matches |
| hint char | (in hint mode) jump to that match |
↑ ↓ ← → | (≤10 matches) cycle selection |
Esc / Ctrl-C / Ctrl-G | cancel (or exit hint mode) |
- ✅ Unique match → auto-jump, no
Enterneeded - 🎯 ≤10 matches → hints auto-appear after ~300ms idle (or press
Tabto show them now) - 🔔 Zero matches after a keystroke → bell, character rejected
⚙️ Config
set -g @jump-key j # default: j (invoked as prefix + j) set -g @jump-key-select J # optional: jump, then visual-select the match set -g @jump-hints 'duhetonasi' # up to 10 hint chars, one per match in hint mode set -g @jump-auto-hint-delay 300 # ms idle before hints auto-show (0 = disable, rounded up to nearest 100ms) set -g @jump-skip-wizard 0 # 1 = never prompt for auto-update on version mismatch
@jump-key-select is a second, opt-in binding: same picker, but on landing it enters copy-mode, begins a selection, and extends it across the matched query — ready to yank.
🔬 How it works
prefix+j → capture-pane -p → display-popup -B → Go TUI
│
type chars → narrow
│
unique match?
│ yes
▼
copy-mode + cursor to (row, col)
- Capture the visible pane to a temp file (
tmux capture-pane -p). - Overlay a borderless
display-popupsized exactly to the pane — perfect in-place redraw. - Render the captured text in the Go TUI: matches highlighted, everything else dimmed.
- Narrow on each keystroke (smart-case substring). Unique match → popup closes, pane drops into copy-mode with the cursor on
(row, col).
🛠️ Development
Requires Go 1.22+ and tmux ≥ 3.2.
make build # CGO_ENABLED=0 static binary at bin/tmux-jump make test # go test ./... make clean
CI (.gitlab-ci.yml) runs go test + builds a static binary on every push; tags trigger a release with a downloadable asset link.
🚧 Known limitations (v1)
- ASCII-first column math — CJK / wide chars may misalign the landing column
- Active pane only — no cross-pane targeting
- Requires tmux ≥ 3.2 for borderless pane-sized popups
🙏 Credits
Inspired by:
schasse/tmux-jump— original tmux hint-based jumperfcsonline/tmux-fingers— the CI + install-wizard pattern lifted hereflash.nvim/leap.nvim— the incremental-narrowing UX
📝 License
MIT — see LICENSE.