tmux-fuzzy-motion

日本語版はこちら

tmux-fuzzy-motion is a CLI for quick cursor jumps inside tmux copy-mode. It scans the current viewport, extracts jump targets, filters them with fuzzy search, and lets you jump with uppercase hints. Roman queries can also match Japanese text through Migemo.

Features

• Works inside tmux copy-mode
• Extracts URLs, paths, filenames, symbols, and general words from the current viewport
• Supports fuzzy matching with fzf
• Supports Migemo matching for alphabetic queries via jsmigemo
• Preserves pane colors while drawing the overlay
• Reuses an external daemon process so matcher and Migemo startup stay warm
• Uses single-key uppercase hints for fast selection
• Opens the UI in a tmux popup instead of creating a persistent scratch window

Requirements

• Node.js 22 or later
• tmux 3.2 or later

Install

npm install -g tmux-fuzzy-motion@latest

If you prefer pnpm:

pnpm add -g tmux-fuzzy-motion@latest

Verify the installation:

tmux-fuzzy-motion doctor

You can also run it without a global install:

npx tmux-fuzzy-motion@latest doctor

tmux Configuration

Add these bindings to your tmux.conf:

bind-key -T copy-mode-vi s run-shell 'tmux-fuzzy-motion start #{pane_id} #{client_tty}'
bind-key -T copy-mode s run-shell 'tmux-fuzzy-motion start #{pane_id} #{client_tty}'

If you want tmux to open the popup directly and avoid the extra run-shell hop, use this instead:

bind-key -T copy-mode-vi s run-shell -C "display-popup -E -B -x '##{popup_pane_left}' -y '##{popup_pane_top}' -w '#{pane_width}' -h '#{pane_height}' 'tmux-fuzzy-motion popup-live #{pane_id}'"
bind-key -T copy-mode s run-shell -C "display-popup -E -B -x '##{popup_pane_left}' -y '##{popup_pane_top}' -w '#{pane_width}' -h '#{pane_height}' 'tmux-fuzzy-motion popup-live #{pane_id}'"

Reload tmux after editing the config:

tmux source-file ~/.tmux.conf

Usage

1. Enter copy-mode.
2. Press s.
3. Type a query in lowercase or symbols.
4. Narrow the candidates with fuzzy matching.
5. For alphabetic queries, Migemo also expands roman input to Japanese matches.
6. Press an uppercase hint to jump immediately.
7. Press Esc or Ctrl-[ to cancel.

Input Keys

• A-Z: select a visible hint immediately
• Enter: select the first visible match
• Esc, Ctrl-[, Ctrl-g: cancel
• Backspace, Ctrl-h: delete one character
• Ctrl-w: delete the previous word
• Ctrl-u: clear the whole query

Commands

tmux-fuzzy-motion start <pane-id> <client-tty>
tmux-fuzzy-motion popup-live <pane-id>
tmux-fuzzy-motion doctor

popup and daemon are internal subcommands. popup-live is intended for direct display-popup bindings.

Doctor

Use doctor to verify the local environment:

tmux-fuzzy-motion doctor

It checks:

• Node.js version
• tmux version
• Migemo dictionary loading

Development

For local development from this repository:

pnpm install

You will need pnpm for the development workflow above.

Build once:

pnpm build

Watch mode:

pnpm run dev

Run the full local check:

pnpm check

Measure popup startup against a warm daemon:

pnpm bench:startup dist/cli.js

Limitations

• Targets are limited to the current viewport
• Designed for copy-mode only
• Query input is ASCII-oriented
• Exact behavior for combining characters is not fully guaranteed
• Requires display-popup, so tmux 3.2 or later is mandatory
• The query is drawn on the bottom row inside the pane, aligned to the right edge