Letter hints over paths, URLs, and hashes on a Rex pane, like tmux-fingers. Go program plus a Lua plugin for Rex, the terminal multiplexer by Superlogical. This file is the map for a coding agent asked to install, configure, extend, or debug it.
go install github.com/xeind/rex-fingers@latest. The binary lands in$(go env GOPATH)/bin/rex-fingers.- Clone this repo to a permanent path, usually
~/.config/rex/plugins/rex-fingers. - In the user's Rex config,
~/.config/rex/init.luaor a file it requires, add:local fingers = dofile(os.getenv("HOME") .. "/.config/rex/plugins/rex-fingers/lua/rex-fingers/init.lua") fingers.setup{ binary = os.getenv("HOME") .. "/go/bin/rex-fingers" }
binarymust be an absolute path. rex config check, thenrex config reload.- Confirm with
rex keymap | grep rex_fingers:alt+fby default, andoverlay = "float". Pane mode is opt-in because Rex for Mac shows a popup listing the key mode's bindings; the user turned it down 2026-11-07.
Every option and its default is in README.md under Configuration. A
walkthrough with a check per step is docs/CONFIGURING.md. Unknown option
names make setup error, so read the list before adding one.
Rex has no API that draws into an existing terminal. The Lua action
rex_fingers:
- Finds the focused pane's rectangle in
session.view. - Captures the pane's screen twice with the terminal block's
formatmethod, as VT sequences and as text withunwrap = true, each to a temp file. The VT redraws the screen row by row; the unwrapped text says which rows the terminal wrapped (screen.Join), so a match can span them and copy whole. - Opens a floating layer with that rectangle, running
rex-fingers show --session S --block B --vt-file F --rows N ...withshell = "none".
The Go program parses the VT into a cell grid, runs the patterns on each
row, draws the dimmed screen with hints over the matches, reads one hint
in raw mode, runs the action, and exits. The floating pane closes on exit
and the program calls rex focus on the original pane.
The key toggles. The action first looks for a floating block labeled
fingers in the window (open_floats). If it finds one, it writes Escape
into it through the block's write method and returns. The program takes
that as a cancel, so the float closes and focus returns as above. Without
this, each press captured the focused float and stacked another over it.
That is overlay = "float". With overlay = "pane" there is no floating
pane. The action:
- Reads the pane's
modes,process,pwd, andsize, and captures the screen as above. - Runs
rex-fingers draw --begin --pid P --vt-file F --rows N --cols Mthroughrex.exec. The program finds the foreground process's tty and writes the dimmed screen with hints straight into it. - Enters the exclusive key mode
fingers. Each hint letter is bound there torex_fingers_key, plain and with each modifier whose action is set. The action runsrex-fingers press --tty T --typed ... --key Kfor each key; the program repaints, or on a full hint restores the pane and runs the action.Escape,q, andCtrl+Crunrex_fingers_cancel, which runsrex-fingers restore. - A run can end without restore: a config reload or an app restart
drops the mode, and the hints stay painted. So
drawwrites$TMPDIR/rex-fingers-<tty>.run.json: the capture paths, the pane's modes, the letters typed, and the text it painted (ui.Painted).pressrewrites it on a repaint;restoreAlldeletes it. The nextdraw --begin, orrestore --recoverfrom the key or cancel action with no run on record, reads it (paneSpec.recover). When the pane's text equals the painted text, the old capture moves under the new paths, the modes come from the file, and\x1b8precedesBegin. Otherwise it deletes the old files.pressand plainrestoretake the modes from the file too, since the Lua flags carry what was read from the painted frame. - The pane's program may write while the hints are up. Every paint ends
with
\x1b8, so that output lands where the program's cursor was. Lua captures each pane as VT (currents) before everypressandrestoreand passes it as--current-file, orcurrent=in a--panespec; VT, not text, see the facts below. When the screen's text differs from the painted text the pane moved on (paneSpec.checkMoved):alignRowsfinds the scroll offset, only the rows that still show the frame are repainted (inpane.RestoreRows), and the cursor is left where the program put it.pressstill picks: a letter on screen names the same match in the capture. It skips the repaint after a first letter, which would cover the new output, and the flash, and reportschanged = true. Before, it refused every pick on a moved pane, and in window scope one pane with a spinner, such as Claude Code, blocked every copy.scripts/test_in_pane.shhas four cases for it. Rows that scrolled into the scrollback keep the hints: no tty write reaches the scrollback, and the terminal block has no method that edits it. Painting on the alternate screen would keep the scrollback clean but discard what the program prints during the run, so the limit stays and the README states it. Reproduce with a pane that prints a line every 300 ms: draw once scrollback exists, wait 3 s, cancel, andrex capture --format=textshows hint letters on the rows that scrolled off.
The in-pane subcommands print one JSON object each. draw returns the
tty and the hint count; press returns done, typed, and paste.
The scope = "window" argument, bound by window_key, always takes the
in-pane path, whatever overlay says: a float covers one pane, and only
the key mode lets one key reach every pane. So the mode and its actions
are registered for both overlays. With it, the action
does the same for every terminal block of the window at once. It reads
them from layer.blocks[] with creator_name == "com.superlogical.terminal",
puts the focused block first, and passes one --pane pid=,vt=,rows=,cols=,cursor=,wrap=
spec per pane. ui.NewSet gives the panes one hint list and ui.PressSet
finds a pick across them; press returns pane, the index of the pane it
came from. A paste goes to the first pane, the one the key was pressed
in, and --cwd is its directory. The run is stored under every member
block, and finish clears and restores them all.
| Path | Holds |
|---|---|
main.go |
CLI: show, patterns, layouts, version; action dispatch |
pane.go |
CLI: draw, press, restore for overlay = "pane", one pane or several --pane specs; each prints one JSON object; runState and recover for a run left without restore |
internal/inpane |
Begin and Restore sequences, TTY(pid) to find the pane's tty |
internal/screen |
VT dump to lines of cells; Parse, Line.Column, Line.CellAt |
internal/patterns |
Builtin map, Default (all but digit), Weight per pattern for hint order, Compile, Set.Find with leftmost-longest overlap rule |
internal/hints |
Generate prefix-free hints; Layouts and Alphabet |
internal/ui |
Overlay: raw mode, draw, key handling, modifiers |
internal/rexcli |
Pane.Size, Capture, Write, Pwd, Focus through the rex CLI |
lua/rex-fingers/init.lua |
setup(opts), the action, rect lookup, capture |
docs/CONFIGURING.md |
user walkthrough |
assets/ |
rex-fingers.icon, the Icon Composer document: claw.svg as a matte Liquid Glass layer over field.svg, Rex's radial gradient sampled from the app icon, and claw-dark.svg, the claw filled with that gradient, shown only in Dark; logo-claw-glass-rex.png and logo-claw-glass-rex-dark.png, its exports at 512 px, the README logo (regenerate with File > Export, Appearance All, 2x); logo-claw-black.svg and logo-claw-white.svg, the bare mark; social-preview.png, the dark render padded to 1280x640 for GitHub |
go test ./... # unit tests: screen, patterns, hints
go vet ./... && gofmt -l .
go build -o bin/rex-fingers . # bin/ is gitignored
rex config check && rex config reload
rex do rex_fingers -b "$REX_BLOCK" # open the overlay on this pane
rex server logs | grep -i lua # Lua errors the check missesAn agent cannot see the overlay. Drive it through the Rex CLI:
S=$(rex new fingers-test --json | jq -r .session_id)
B=$(rex api call -s $S session.view '{}' | jq -r '.windows[0].layers[0].blocks[0].block_id')
sleep 1.5
rex send -s $S -b $B 'echo /tmp/a https://example.com' && rex send-key -s $S -b $B enter
sleep 1
rex do rex_fingers -s $S -b $B
sleep 2
OB=$(rex api call -s $S session.view '{}' | jq -r '.windows[0].layers[] | select(.kind!="tiled") | .blocks[0].block_id')
rex capture -s $S -b $OB --format=vt --trim | tail -3 # hints are visible as SGR sequences
rex send -s $S -b $OB a; sleep 1.5; pbpaste # the first match
rex kill $SIn a session no app renders, the overlay stays 80x24 and the capture wraps at column 80. That is a test artifact. Only a real key press in the app sizes the overlay, so layout questions need the user's eyes or a screenshot.
The in-pane path needs a client for the key mode, so a headless session
cannot press a hint. It can draw and restore. testdata/width-cases.txt
holds one line per character-width case:
S=$(rex new flag-probe --json | jq -r .session_id); sleep 1.5
B=$(rex api call -s $S session.view '{}' | jq -r '.windows[0].layers[0].blocks[0].block_id')
rex send -s $S -b $B 'clear; cat testdata/width-cases.txt' && rex send-key -s $S -b $B enter; sleep 1
rex block call -s $S -b $B format '{"format":"vt"}' | jq -j .content > /tmp/flag.vt
P=$(rex block call -s $S -b $B process | jq -r .foreground.pid)
go build -o bin/rex-fingers . && ./bin/rex-fingers draw --begin --pid $P --vt-file /tmp/flag.vt --rows 24 --cols 80
rex capture -s $S -b $B --format=text --trim | head -9 # every row: text, space, hint over the slash
./bin/rex-fingers restore --pid $P --vt-file /tmp/flag.vt --rows 24
rex kill $Srex keymap | grep -c fingers/ counts the mode's bindings; the app lists
every one while the mode is active.
Stale hints: draw --begin as above, then rex do rex_fingers_cancel -s $S -b $B. The pane must show no hint letters and modes must report 7
and 25 set. Only the restore tells, since a second draw paints the same
frame whether or not it recovered the first run. Take --rows and
--cols from the block's size method; a headless pane is not always
80x24. Capture to a new file each time. A capture written over the first
run's path is the painted frame, and recover refuses it.
Window scope is testable the same way with two panes: rex split -s $S -b $B --split=below --focus=false --json gives a second block, each gets
its own capture and --pane spec, and one draw call takes both. A
press --key with the same specs needs no client. Check that the hint
letters differ between the panes, that press reports the right pane
index and clipboard text, and that both panes are restored. Through Lua,
rex do rex_fingers -s $S -b $B scope=window runs up to the key mode and
then restores, since a headless session has no client to enter it.
- A floating pane in Rex for Mac is two rows shorter than the pane under
it;
--alignpicks which rows to drop. The pane reports 80x24 until the app sizes it, soui.waitForSizepolls up to 1.5 s anddrawreruns on SIGWINCH. - Rex for Mac build 1825 did not forward OSC 52 to the clipboard; build
1859 does, from a pane's tty, within a second. Copy still uses
pbcopyor a Linux equivalent and writes OSC 52 too, into the pane's tty in pane mode, so the app's own copy feedback fires when it has one. - A pane whose program exits within a moment stays open in Rex. The program lives at least 400 ms.
rex do rex_fingersfrom the CLI:rex.client.queuesucceeds and the app refuses the queuedclient.mode.enterafter the action returns, so no restore runs and the hints stay. A key press in the app works. The run file above covers the leftover.- With autowrap off, the cursor stays on the last column after a row that
fills the width, so erase-to-end-of-line there takes that cell.
ui.drawskips\x1b[Kon a full row. - The user's shell is nushell. Its line editor holds the tty in raw mode
at the prompt, so output from a background process gets no carriage
returns and staircases across the screen. Not a fingers effect; count
occurrences, not rows, when a test checks such output. Nushell also
renders
echo a b cas a table. - macOS checks a freshly built binary on first run, about 360 ms. Run it once after building before judging latency.
session.viewnestssplit.beforeandsplit.after, each withrectin window fractions; a floating layer's layout is relative to its bounds.- Go regexp accepts
(?<match>...); the tmux-fingers patterns port as is. Tests a regexp cannot state live inpatterns.checksby name:shaandipv6must stand alone and contain a digit, sofeedbackandPane::Annotateare not matches. - The
formatmethod'sunwrap = truejoins soft-wrapped rows; the VT format with it returns fewer rows than the screen has.inpane.Beginturns auto-wrap off, so painting must stay row by row from the wrapped VT; the unwrapped text is used only to markLine.Wrap. A row joins the next when it is exactly the pane width and the unwrapped text contains both rows run together. A row wrapped before a wide character ends one cell short and does not join. - The
formatmethod returns the scrollback and the screen. Its VT keeps every screen row; its text drops blank rows at the foot of the screen, so the lastrowslines of the text reach into the scrollback. A current capture compared against the painted frame must be VT: from text,alignRowsfound no match on a half-empty screen with scrollback, and restore repainted nothing. - Rex's emulator is Ghostty. With grapheme clustering (DEC mode 2027) off,
it sizes each code point on its own: a regional indicator, half of a
flag, is 2 columns, so a flag is 4.
go-runewidthsays 1, andcellsOfoverrides it. The terminal block'smodesmethod reports mode 2027 asgrapheme_cluster; it was off in every pane measured. With it on, Ghostty would draw a flag pair or a ZWJ sequence as one 2-column cell, and the parser does not handle that yet. - A key mode belongs to one client, and a mode binding must name an
action; a Lua function binding is not allowed in a mode. The action's
ctxdoes not say which key ran it, so each hint key needs its own binding with{ key, mod }args. The app lists every binding of the active mode as a row of title plus args, so the mode binds only the letters and modifiers that can be pressed. No setting hides that panel. The user defaultWorkspace.showsKeySequenceHintsincom.superlogical.rex, Settings > Terminal > Keyboard > Show key sequence hints, hides only the panel for a pending prefix such as Ctrl+B, and the app reads it at launch only. Tested 2026-11-07: with it off and the app relaunched, the mode list still shows.
- Every pattern change needs a case in
internal/patterns/patterns_test.go. - Styles name palette slots (
38;5;N,48;5;N), never hex colors, so they follow the theme. - No shell in Lua strings; the Lua side only builds an argv.
- Options are declared once in
defaultsininit.luaand documented inREADME.mdunder Configuration, with the same names and defaults. - Keep tmux-fingers' names and defaults where Rex allows it.
- Tested against Rex for Mac 0.1.0 (1825), CLI
0.0.1793741575-g1b6654. Rex is in beta; recheck the facts above when a build changes behavior.