flatten.nvim: piping terminal files into the Neovim instance you already have open

The problem is the second editor, not the file path

Open a file from a terminal and you normally get a nested Neovim: a new instance inside the shell, with its own buffers, its own plugins and its own idea of where you are. The repository description compares the plugin to code -r on steroids, which is the shape of the problem. flatten.nvim removes the nesting by having the guest instance, the one your terminal launched, forward its arguments to a host instance and then get out of the way. The README lists the resulting features: opening files from terminal buffers without creating a nested session, blocking for git commits, a pipe from a terminal into a new Neovim buffer, command passthrough from guest to host, and the ability to flatten WezTerm and Kitty tabs or panes that share a working directory into the same instance. The audience is narrow and specific: people who run Neovim as a long lived process and treat the terminal as a way of starting work, not as a place to edit files.

Blocking decides whether the terminal waits for you, and passthrough carries commands back

The key behaviour is blocking. When a guest instance opens a file of a blocking filetype, the guest waits until the host closes the file, so a git commit message editor behaves the way it does in a normal session instead of detaching into a separate process. By default the blocking set is small, containing gitcommit and gitrebase only, and you extend it with a table of filetype to boolean entries. There is also a way to force blocking regardless of filetype from the command line, using a global variable, which the README shows in the usage section. Command passthrough is the mirror image of blocking: a command given to the guest with --cmd is executed in the host before files open, and a command given with + is executed in the host afterwards. The option disable_cmd_passthrough turns that off, and the two nesting options, nest_if_no_args and nest_if_cmds, decide when the guest should keep its own instance instead of being flattened.

Window placement is where the configuration surface gets deep

The window options are the most detailed part of the documentation, and they are where a user spends real time. The open option accepts current, alternate, split, vsplit, tab, smart or a custom handler function, and the README explains that alternate opens the file in the alternate window, current in the current one, smart picks automatically between the alternate window, another available window and a new split. The diff option has its own set for split, vsplit, tab_split and tab_vsplit. Both accept a Flatten.OpenHandler, a function that receives an OpenContext and returns a window number and optionally a buffer. The context object is where the plugin exposes internals: the files list passed to the host, the full argv from the guest, information about any stdin buffer, the guest's working directory, and the data returned by the guest_data hook. That is a real API for building custom behaviour, and it is also the surface most likely to change before 1.0.0.

Terminal integrations are opt-in, and Kitty cannot flatten by working directory

The wezterm and kitty integrations sit under an integrations table and both default to false. Enabling the wezterm integration means WezTerm tabs running in the same working directory are flattened into the same Neovim instance, which is a natural fit for a multiplexer that is already directory aware. The kitty integration flattens Kitty tabs into the same instance, but the README states plainly that flatten by cwd is not supported on Kitty yet and invites pull requests. That is a small line in the docs with a large practical effect: on Kitty, flattening still works, but the grouping rule is weaker, so tabs in different directories may end up in one instance or not be grouped the way you expect. The hooks are what make both integrations possible in the first place, since should_nest receives a channel and decides whether a guest should be flattened into the host's instance or open a new one.

Installing through lazy.nvim or rocks.nvim, and the Neovim version floor

The README states that Flatten requires nvim 0.10 or newer, which is the first thing to check before anything else. There are two documented install paths. The lazy.nvim path registers the plugin with a spec, and the comment in the snippet explains the two options that matter for this particular plugin: config = true makes the plugin call its own setup function, and lazy = false with a high priority makes it load first, to minimise the delay when opening a file from a terminal. That ordering requirement is the tell that this plugin sits on a hot path.

require("lazy").setup({
  {
    "willothy/flatten.nvim",
    config = true,
    -- or pass configuration with
    -- opts = {  }
    -- Ensure that it runs first to minimize delay when opening file from terminal
    lazy = false,
    priority = 1001,
  },
  --- ...
})

The rocks.nvim path goes through LuaRocks, since the plugin is published as a rocks module, and the install is a single Ex command. After that, the setup call lives in a plugin file of your own.

:Rocks install flatten.nvim

The first real use is the command you would already type in a terminal, and the file opens in the instance you already have rather than in a nested one.

nvim file1 file2

The configuration block itself is plain Lua, and the parts most people change are the blocking set, the nesting flags and the window placement.

  block_for = {
    gitcommit = true,
    gitrebase = true,
  },
  disable_cmd_passthrough = false,
  nest_if_no_args = false,
  nest_if_cmds = false,
  window = {
    open = "current",
    diff = "tab_vsplit",
    focus = "first",
  },

The defaults snippet and the option reference disagree about window.open

There is a small inconsistency in the documentation that will cost you a debugging session if you trust the wrong half of it. The defaults block shows window.open set to current, and the window.focus option to first. The option reference section states that the default is alternate, and separately lists first as the default for focus. The two statements cannot both be the effective default. The practical consequence is that a file may open in a different window than you expect after an update, and that the behaviour you see does not match either document. Set window.open explicitly in your configuration and the ambiguity stops mattering. It is also a reasonable signal about how much of this plugin you should configure by reading the source rather than the README.

Pre-1.0 with breaking changes in flight and a last push on 2026-06-19

The README opens with a note that Flatten is undergoing some breaking changes on the road to the release of a stable 1.0.0, and points at issue 87 for the details. That is the honest headline for anyone planning to depend on the API. The published releases tell the same story from the other side: v0.5.1 from 2024-01-26, v0.5.0 from 2023-11-28 and v0.4.1 from 2023-09-24, with no release since the start of 2024 even though the last push was on 2026-06-19. The code has moved on since the last tag. The licence is MIT, which means you can read, modify and redistribute the plugin without friction, and the plugin is published on LuaRocks as well as GitHub, so installation does not depend on either one being reachable.

Editorial conclusion

flatten.nvim suits a Neovim user who keeps one long lived instance open and is tired of nested editors when a file is launched from a terminal, and who is willing to read Lua hooks to make it fit. It does not suit someone who wants a stable, documented API today, since the README points to an open issue about breaking changes on the way to 1.0.0. Before you build on it, confirm your Neovim is 0.10 or newer, read issue 87 for the direction of the rewrite, and set window.open explicitly, because the documented default and the defaults snippet in the README disagree.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. willothy/flatten.nvim on GitHub