Neovim and tmux navigation¶
Use Ctrl-H/J/K/L to move through Neovim splits → tmux panes → Graffitty panes. Each layer handles its own neighbors and passes navigation outward only at an edge. Navigation never wraps.
Follow the setup below. If you do not use tmux, skip its setup.
1. Enable navigation in Graffitty¶
Enable navigation in ~/.config/graffitty/server.toml:
[navigator]
enabled = true
filetree = true
algorithm = "spatial" # Alternatives: "weighted", "nearest"
[navigator.bindings]
"ctrl+h" = "left"
"ctrl+j" = "down"
"ctrl+k" = "up"
"ctrl+l" = "right"
Keep gft on PATH. This integration supports macOS and Linux.
2. Configure Neovim¶
Install graffitty.nvim with lazy.nvim:
{
"graffitty/graffitty.nvim",
opts = {},
keys = {
{ "<C-h>", function() require("graffitty.navigator").move_left() end, desc = "Navigate left" },
{ "<C-j>", function() require("graffitty.navigator").move_down() end, desc = "Navigate down" },
{ "<C-k>", function() require("graffitty.navigator").move_up() end, desc = "Navigate up" },
{ "<C-l>", function() require("graffitty.navigator").move_right() end, desc = "Navigate right" },
},
}
Normal mode is the default. To also navigate in insert and terminal modes, set
opts.navigator.modes = { "n", "i", "t" } and mode = { "n", "i", "t" }
on each mapping.
Neovim selects its own splits, then tmux neighbors, and invokes gft select-pane
only at the outer edge. If you do not use tmux, skip the next section.
3. Configure tmux¶
Add the plugin before TPM initialization in ~/.tmux.conf:
Reload with tmux source-file ~/.tmux.conf, then press prefix + I to install.
Use prefix + U to update. Keep your existing TPM initialization line if present.
Without TPM, use the manual tmux bindings.
Behavior¶
- Ctrl-H/J/K/L selects left/down/up/right respectively.
- Foreground applications retain their keys; Neovim handles its mappings.
- Copy mode keeps its keys, and a zoomed tmux pane stays zoomed.
- One tmux layer is supported. Plain SSH passes keys through without handing navigation back to local Graffitty.
- Outside Graffitty, Neovim and tmux navigation still work and stop at the edge.
Send a navigation key literally¶
To pass a navigation key to the terminal instead, add this to client.toml:
The tmux bindings use GRAFFITTY_BIN when Graffitty supplies it.
To send a navigation key literally, press the Graffitty prefix, then Ctrl-L, then the key.
Select panes from a script¶
See Select a pane for directional and explicit CLI targets.