Seamless navigation and resizing between Neovim splits and Herdr panes. Makes Herdr terminal splits behave like native Neovim windows — move and resize as if they were all part of the same editor.

Inspired by smart-splits.nvim, ported to Herdr's CLI.

Features

• Seamless navigation: Same keys work in Neovim and plain shells — Herdr forwards them to Neovim when appropriate, Neovim delegates to Herdr at edges.
• Seamless resizing: <M-h/j/k/l> resizes Neovim splits natively, delegates to Herdr when a window fills the terminal.
• at_edge behaviours: wrap (default), stop, split, or a custom function.
• Plugin-aware: Ignores snacks/neo-tree/dadbod-ui/aerial sidebars and embedded floats (zindex < 50) by default — your keybinds never get trapped inside a picker.
• Smart unzoom + wrap-around: Auto-unzooms when leaving a zoomed pane. At a layout edge, navigation wraps to the opposite side — crossing into a sibling Herdr pane when one exists (e.g. pane | nvim → ctrl+l wraps to the pane), otherwise wrapping within Neovim. Herdr-pane navigation also wraps around at edges (past the last pane → the first). Does not unzoom when moving between Neovim splits in one pane.
• Count prefix support: 3<C-h> moves three splits left; 5<M-l> resizes five steps right.

Requirements

• Neovim ≥ 0.10
• Herdr ≥ 0.7.0 (for plugin actions)

Installation

Three steps — install on both the Herdr side and the Neovim side, then add keybinds.

1. Install the Herdr plugin

This provides the nav- and resize- actions that Herdr keybinds invoke.

# From GitHub (once published):
herdr plugin install lmilojevicc/herdr-splits.nvim
Local development:
herdr plugin link /path/to/herdr-splits

2. Install the Neovim plugin

lazy.nvim

{
  'lmilojevicc/herdr-splits.nvim',
  -- For local development, swap the repo line for dir = '/path/to/herdr-splits'
  -- (see "Local development" below).
  cond = vim.env.HERDR_ENV == '1',
  event = 'VeryLazy',
  -- Optional: auto-sync the Herdr-side scripts when lazy updates this plugin.
  -- Requires autosyncherdr = true in setup() below to take effect.
  -- build = ':lua require("herdr-splits").sync_herdr()',
  config = function()
    require('herdr-splits').setup({
      -- Defaults shown. All fields optional.
      default_amount = 0.03,       -- Herdr resize ratio
      neovim_amount = 3,           -- Neovim resize cells
      at_edge = 'wrap',            -- 'wrap' | 'stop' | 'split' | function
      ignored_buftypes = { 'nofile', 'quickfix', 'prompt', 'help', 'terminal' },
      ignored_filetypes = {
        'NvimTree',
        -- sidebars
        'neo-tree',
        'snacks_dashboard',
        'snacks_explorer',
        'snacks_picker',
        -- DB / REPL / data sidebars
        'dadbod-ui',
        'dbout',
        -- outlines / symbols
        'aerial',
        'Outline',
        -- diagnostics / quick lists
        'Trouble',
        'quickfix',
      },
      movecursorsame_row = false,
      herdrbin = nil,                -- auto-detected from HERDRBIN_PATH
      floatingzindexmax = 50,       -- floats with zindex < this are treated as embedded sidebars
      ignore_previewwindows = false,  -- opt-in: also treat previewwindow windows (e.g. .dbout) as sidebars
      -- autosyncherdr = true,      -- opt-in: sync Herdr-side scripts on update
      -- Managed keys — written to the generated herdr-splits.conf so the
      -- Herdr-side scripts agree. Pass Neovim notation (e.g. <M-Left>).
      nav_keys    = { left = '<C-h>', down = '<C-j>', up = '<C-k>', right = '<C-l>' },
      resize_keys = { left = '<M-h>', down = '<M-j>', up = '<M-k>', right = '<M-l>' },
      unzoomonnav = true,   -- auto-unzoom when navigating away from a zoomed pane
      navatedge    = 'wrap', -- 'wrap' | 'stop' — Herdr pane-boundary wrap (distinct from at_edge)
    })
  end,
  keys = {
    { '<C-h>', function() require('herdr-splits').movecursorleft() end,  desc = 'Navigate left' },
    { '<C-j>', function() require('herdr-splits').movecursordown() end,  desc = 'Navigate down' },
    { '<C-k>', function() require('herdr-splits').movecursorup() end,    desc = 'Navigate up' },
    { '<C-l>', function() require('herdr-splits').movecursorright() end, desc = 'Navigate right' },
    { '<M-h>', function() require('herdr-splits').resize_left() end,  desc = 'Resize left' },
    { '<M-j>', function() require('herdr-splits').resize_down() end,  desc = 'Resize down' },
    { '<M-k>', function() require('herdr-splits').resize_up() end,    desc = 'Resize up' },
    { '<M-l>', function() require('herdr-splits').resize_right() end, desc = 'Resize right' },
  },
}

packer.nvim

use {
  'lmilojevicc/herdr-splits.nvim',
  config = function()
    require('herdr-splits').setup()
  end,
}

3. Add keybinds to Herdr config

Add these to ~/.config/herdr/config.toml, then run herdr server reload-config:

[[keys.command]]
key = "ctrl+h"
type = "plugin_action"
command = "herdr-splits.nav-left"
[[keys.command]] key = "ctrl+j" type = "plugin_action" command = "herdr-splits.nav-down"
[[keys.command]] key = "ctrl+k" type = "plugin_action" command = "herdr-splits.nav-up"
[[keys.command]] key = "ctrl+l" type = "plugin_action" command = "herdr-splits.nav-right"
[[keys.command]] key = "alt+h" type = "plugin_action" command = "herdr-splits.resize-left"
[[keys.command]] key = "alt+j" type = "plugin_action" command = "herdr-splits.resize-down"
[[keys.command]] key = "alt+k" type = "plugin_action" command = "herdr-splits.resize-up"
[[keys.command]] key = "alt+l" type = "plugin_action" command = "herdr-splits.resize-right"

Note for macOS: Terminals treat Option as a special character modifier by default. You need to set Option = Alt/Meta:

>

- Ghostty: macos-option-as-alt = true

- Alacritty: optionasalt = "Both"

- kitty: macosoptionas_alt yes

- iTerm: Profiles → Keys → Left Option key → Esc+

>

If you're using smart-splits.nvim for tmux, add cond = vim.env.HERDRENV ~= '1' to its spec so the two plugins don't conflict.

Auto-unzoom and wrap-around

Auto-unzoom. When you navigate away from a zoomed pane, herdr-splits unzooms first so the destination is visible — whether you're crossing into a sibling Herdr pane or wrapping at a layout edge. It does not unzoom when moving between Neovim splits inside the same pane.

Wrap-around. When you reach a layout edge in the direction you pressed (nowhere further to go that way), the default wrap behaviour continues on the opposite side:

• If a Herdr pane sits on the opposite side, focus crosses into it — so

pane | nvim wraps ctrl+l back to the pane, and pane | nvim win1 | win2 wraps from win2 to the pane. With navatedge=stop (see below) this cross-to-opposite-pane is suppressed and the wrap stays within Neovim instead.

• Otherwise it wraps within Neovim (smart-splits default).
• Between plain Herdr panes, navigation wraps around at edges too (past the

last pane → the first).

• Wrap works even when you're on a sidebar (dbui, neo-tree, quickfix, ...),

so you can leave it at an edge; only embedded floating overlays are gated.

To disable auto-unzoom entirely, pass unzoomonnav = false to setup():

require('herdr-splits').setup({ unzoomonnav = false })

These options are written to a generated herdr-splits.conf (default ~/.config/herdr/plugins/config/herdr-splits/herdr-splits.conf; print the path with herdr plugin config-dir herdr-splits) so the Herdr-side scripts agree — you configure them once, from setup(). **Do not hand-edit that file:** it is regenerated on every setup(). Any values already present are adopted once the first time setup() runs after an upgrade, then overwritten thereafter. Set HERDRSPLITSCONFIG to override the path on both sides.

To stop at layout edges instead of wrapping, pass navatedge = 'stop':

require('herdr-splits').setup({ navatedge = 'stop' })

This single switch controls wrap-across-boundary on both sides:

• Plain Herdr panes: wrap (the default) wraps to the opposite pane at an

edge; stop halts.

• Neovim edge wrap: when Neovim's at_edge='wrap', wrap (the default)

lets the wrap cross to the Herdr pane on the opposite side (e.g. ctrl+l from the last nvim split lands on the pane); stop keeps the wrap within Neovim (e.g. ctrl+l from the last split cycles to the first split instead of leaving Neovim). atedge='stop' halts regardless of navat_edge.

Note: at_edge (Neovim window-edge behaviour: wrap/stop/split/function) and navatedge (Herdr pane-boundary wrap: wrap/stop) are two different things despite the shared name — at_edge is Neovim-side only and is not written to the conf.

Note: when a pane is zoomed and unzoomonnav=false, the edge flags can't be trusted so stop can't be detected on the plain-pane side — navigation proceeds in the requested direction in that case. With the default unzoomonnav=true, pressing toward an edge while zoomed first unzooms the pane (so the edge can be detected) and then halts — the pane unzooms even though focus doesn't move.

To remap the keys forwarded into Neovim, pass navkeys / resizekeys to setup() in Neovim notation (e.g. <M-Left>). Override only the directions you rebind; the rest keep their defaults. By default the scripts forward ctrl+h/j/k/l for navigation and alt+h/j/k/l for resizing — the chords the documented Neovim keymaps bind:

require('herdr-splits').setup({
  nav_keys    = { left = '<M-Left>', down = '<M-Down>', up = '<M-Up>', right = '<M-Right>' },
  resize_keys = { left = '<M-S-Left>', down = '<M-S-Down>', up = '<M-S-Up>', right = '<M-S-Right>' },
})

• Pass Neovim notation in setup() (<C-h>, <M-Left>); it is translated to the Herdr chord notation (ctrl+h, alt+left) the generated conf writes and herdr pane send-keys accepts.
• Any direction left unset keeps its default.
• The chord forwarded into Neovim must match the Neovim keymap that catches it: <M-Left> in setup() is the same key alt+left the script forwards, so keep your vim.keymap.set in sync with nav_keys.

Eager load required for custom keys. The generated conf is written by

setup(), so custom navkeys/resizekeys need setup() to run eagerly

or at VeryLazy — do not lazy-load this plugin only from the same

custom key mappings it must publish. Otherwise the conf carrying your custom

chords isn't written before Herdr forwards them, and those keys can't reach

Neovim to trigger the lazy load. The recommended spec above already uses

event = 'VeryLazy'.

Local development

Both sides load straight from your clone, so edits take effect immediately (on the Herdr side; Neovim picks them up on reload/restart).

• Link the Herdr plugin to your local repo:

herdr plugin link /path/to/herdr-splits

• Point lazy.nvim at the same path — change the first line of the spec

from the GitHub repo to dir:

{
     dir = '/path/to/herdr-splits',
     cond = vim.env.HERDR_ENV == '1',
     -- ...rest of the spec unchanged
   }

Run herdr plugin list to confirm it shows herdr-splits ... [local:/...]. To switch back to the published version: herdr plugin unlink herdr-splits, then herdr plugin install lmilojevicc/herdr-splits.nvim, and revert the lazy spec to 'lmilojevicc/herdr-splits.nvim'.

Lua API

require('herdr-splits').setup(opts)
-- Resize (amount defaults to config.default_amount, multiplied by count prefix) require('herdr-splits').resize_left(amount) require('herdr-splits').resize_down(amount) require('herdr-splits').resize_up(amount) require('herdr-splits').resize_right(amount)
-- Navigate (opts can override samerow and atedge per-call) require('herdr-splits').movecursorleft({ samerow = true, atedge = 'stop' }) require('herdr-splits').movecursordown(opts) require('herdr-splits').movecursorup(opts) require('herdr-splits').movecursorright(opts)

Compatibility

herdr-splits.nvim ships with an opinionated default ignoredfiletypes list so your resize keybinds don't get trapped inside common sidebars and pickers. These filetypes are treated as sidebars: split-at-edge and Herdr resize delegation are skipped from them, and the flag is passed to a custom atedge function as is_sidebar. wrap, however, still works from a sidebar so you can leave it (e.g. ctrl+l on a dadbod-ui drawer wraps to the opposite side); only embedded floating overlays are gated.

The default ignored_filetypes covers:

• NvimTree — nvim-tree/nvim-tree.lua default file tree (buftype=nofile, winfixwidth).
• neo-tree — nvim-neo-tree/neo-tree.nvim LazyVim default (winfixwidth sidebar).
• snacksdashboard / snacksexplorer / snackspicker — folke/snacks sidebar/picker windows (the float case is handled by isembeddedfloatingwindow below).
• dadbod-ui / dbout — kristijanhusak/vim-dadbod-ui drawer and tpope/vim-dadbod preview result buffer.
• aerial / Outline — code-outline sidebars.
• Trouble / quickfix — diagnostics and quickfix lists.

The default ignored_buftypes covers nofile, quickfix, prompt, help, and terminal.

Embedded floating windows (snacks explorer in float mode, neo-tree in float mode, aerial in float mode) are detected via the zindex < floatingzindexmax heuristic (default threshold 50, Neovim's default float zindex) and treated as sidebars for navigation/resize decisions. Override the threshold via the floatingzindexmax config field.

Add your own at runtime from any VeryLazy autocmd:

require('herdr-splits').addignoredfiletype('lazy')
require('herdr-splits').addignoredbuftype('help')

Debug with :checkhealth herdr-splits (Neovim ≥ 0.10) to see which filetypes/buftypes are ignored, whether Herdr is in session, and whether the current window is classified as a sidebar.

If you want to completely replace the default list (e.g. to opt out of one of the entries), note that vim.tbldeepextend('force', M, opts) concatenates the ignoredfiletypes / ignoredbuftypes tables you pass; you keep what you pass AND the defaults are appended. To opt out, assign directly after setup():

require('herdr-splits').setup({ ignored_filetypes = {} })  -- inherit nothing
require('herdr-splits').addignoredfiletype('mything')     -- then add back what you want

How It Works

Two sides cooperate for seamless two-way navigation:

You press C-h in a Herdr pane:
┌─ Herdr intercepts the key (plugin_action keybind)   │   ├─ Is the focused pane running Neovim?   │   │   │   ├─ YES → forward "ctrl+h" into that pane   │   │         └─ Neovim plugin receives it   │   │              ├─ Has a window to the left? → wincmd h   │   │              └─ At Neovim edge? → herdr pane focus --direction left   │   │   │   └─ NO (plain shell, etc.) → herdr pane focus --direction left   │   └─ Result: same keys move you everywhere

Navigation

1. Try moving within Neovim (wincmd h/j/k/l)
   ├─ Window changed → done (stayed within Neovim splits)
   └─ Window didn't change → at Neovim edge
        ├─ Zoomed? → unzoom first (neighbours are reliable once visible)
        ├─ Check if Herdr is running (HERDR_ENV=1)
        ├─ Check if Herdr pane has a neighbour in this direction
        │   └─ Yes → herdr pane focus --direction → done
        └─ No (at both Neovim AND Herdr edge) →
             apply at_edge behaviour (wrap crosses to the opposite Herdr
             pane if one exists and navatedge=wrap (the default), else
             wraps within Neovim)

Resizing

1. Only one Neovim window in this dimension AND fills terminal?
   └─ Yes → herdr pane resize --direction --amount <ratio> → done
Otherwise:
   └─ Native Neovim resize with position-aware +/- operators

Float and embedded-float classification

Two predicates classify the current window before any nav/resize decision:

• win.isfloating(winid) — nvimwingetconfig(winid).relative ~= '' (Neovim's built-in float check).
• win.isembeddedfloatingwindow(winid) — true only for floats with zindex < floatingzindex_max (default 50); matches snacks/neo-tree/aerial float-mode sidebars.

True floats forward to Herdr; embedded floats behave as sidebars (no movement, no Herdr delegation).

Herdr Detection

Detected automatically through environment variables Herdr injects into every pane:

• HERDR_ENV=1 — set when running inside a Herdr-managed pane
• HERDRPANEID — the public pane ID (e.g., w1:p1)
• HERDRBINPATH — path to the herdr binary (for subprocess calls)

Comparison with vim-herdr-navigation

| Feature | vim-herdr-navigation | herdr-splits.nvim | | --------------------------- | -------------------- | ---------------------------- | | Navigation | ✓ | ✓ | | Resizing | ✗ | ✓ | | at_edge behaviours | ✗ | wrap / stop / split / custom | | Count prefix | ✗ | ✓ (3 = move 3 left) | | Auto-unzoom + wrap-around | ✗ | ✓ | | Floating window handling | ✗ | ✓ | | Herdr plugin (for keybinds) | ✓ | ✓ | | Neovim plugin | ✓ | ✓ |

Updating

The Neovim side (lua) auto-updates via lazy.nvim — it pulls main on LazySync. The Herdr side (the bash scripts under the Herdr-managed checkout) does not auto-update by default: Herdr v1 has no herdr plugin update, so a managed checkout stays frozen at the commit it was installed from.

Option A — opt into automatic sync (recommended): set autosyncherdr = true in setup(). The plugin then reinstalls the Herdr-managed checkout pinned to the exact commit lazy fetched, so the bash scripts always match the lua side. It is a no-op when already in sync, when in local-dev (plugin link) mode, or when the herdr binary is unavailable.

Also add a build hook to attempt synchronization after lazy installs or updates when configuration is already active. Normal setup-time synchronization still provides convergence on startup:

{
  'lmilojevicc/herdr-splits.nvim',
  build = ':lua require("herdr-splits").sync_herdr()',
  config = function()
    require('herdr-splits').setup({ autosyncherdr = true })
  end,
}

Option B — manual: after an update, re-run herdr plugin install lmilojevicc/herdr-splits.nvim to refresh the Herdr-side scripts.

Release notes for each version live in GitHub Releases.

License

MIT