smart-splits.nvim

<div align="center">

# 🧠 `smart-splits.nvim`

</div>

> [!NOTE]
> This repo recently moved to a new `smart-splits-nvim` GitHub org!
> See [#488](https://github.com/mrjones2014/smart-splits.nvim/issues/488) / [#492](https://github.com/mrjones2014/smart-splits.nvim/issues/492)
> for details.

🧠 Smarter and more intuitive split pane management for Neovim. Resize splits using a mental model of left/right/up/down instead of wider/narrower/taller/shorter. Navigate seamlessly between Neovim windows and terminal multiplexer panes with a clean, backend-driven architecture.

**Key features:**

- Intuitive resize model that matches how you think about splits
- Seamless navigation between Neovim and multiplexer panes
- Modular architecture: multiplexer support lives in separate plugins
- Configurable edge behavior: wrap, stop, split, or custom logic
- Ignore lists for buffers and filetypes
- Count-aware resizing with `v:count1` support

<video src="https://github.com/user-attachments/assets/e516399d-0c49-4c3d-b748-3ee0e4262898"></video>

**Table of Contents**

<!--toc:start-->

- [🧠 `smart-splits.nvim`](#-smart-splitsnvim)
  - [Requirements](#requirements)
  - [Installation](#installation)
  - [Quick Start](#quick-start)
  - [Configuration](#configuration)
    - [Ignore Lists](#ignore-lists)
    - [Floating Windows](#floating-windows)
    - [At Edge Behavior](#at-edge-behavior)
  - [Keybindings](#keybindings)
  - [Lua API](#lua-api)
  - [Commands](#commands)
  - [Backends](#backends)
    - [Available Backends](#available-backends)
    - [Multiple Backends](#multiple-backends)
    - [Writing a Backend](#writing-a-backend)
  - [Migration from v2](#migration-from-v2)
  - [Troubleshooting](#troubleshooting)
  <!--toc:end-->

## Requirements

- Neovim 0.11 or newer
- (Optional) A terminal multiplexer with a supported `smart-splits` backend plugin (e.g. `smart-splits-nvim/backend-zellij-lua`)

## Installation

**smart-splits.nvim** is the core plugin. Multiplexer backends (Zellij, Ghostty, etc.) are separate plugins you install alongside it.

With [lazy.nvim](https://github.com/folke/lazy.nvim):

```lua
return {
  'smart-splits-nvim/smart-splits.nvim',
  version = '^3.0.0',
  -- optional: install a backend
  dependencies = {
    {
      'smart-splits-nvim/backend-zellij-lua',
      main = 'smart-splits-backend-zellij-lua',
      opts = {
        --[[ backend-specific options go here ]]
      },
    },
  },
  opts = {
    mux = { backend = 'smart-splits-backend-zellij-lua' },
  },
}
```

Calling `setup()` is optional. Without it you get the defaults and no multiplexer integration.

## Quick Start

<details>

  <summary>Minimal working example configuration with the Zellij backend (click to expand)</summary>

```lua
-- Install smart-splits.nvim and a backend
return {
  'smart-splits-nvim/smart-splits.nvim',
  version = '^3.0.0',
  dependencies = {
    { 'smart-splits-nvim/backend-zellij-lua', main = 'smart-splits-backend-zellij-lua' },
  },
  opts = {
    mux = { b