Akmadan23/local-session.nvim

github

session

5

0

1

1

CREATED

2026-01-04

UPDATED

2026-01-17

---

local-session.nvim

A fast, minimal and implicit session manager configured in lua. It does not aim to replace standard vim session, it just offers a different approach, more minimal and implicit.

How does it work?

Unlike standard vim sessions, where you have to explicitly specify the path to the session file, with local-session.nvim you just create a file named .session.lua (the name can be changed in the configuration) in the directory where you always open the same files (hence local), and when you launch neovim from that directory with no arguments the session will be automatically loaded.

What is a session file?

A session file is a specification of which files will open automatically on vim startup, where you can specify splits, tabs, custom options and callback scripts.

Creating a session file

A session file is a lua file that must return a table (which will be referred to as the root table) with the following properties:

[!IMPORTANT] All fields except path are optional. path can be omitted in the root table only if there is a valid tabs field.

Footnotes:

1. non-absolute paths are considered relative to the position of the session file.
2. split and vsplit conflict with each other. If both are specified in the same file, only split will be applied.
3. a File can be a string containing its path or a table with the same properties listed above, except tabs and config which are only accepted in the root table.

Examples

return {
  -- the main file to edit
  "mainFile",

  -- file to edit in a split (it can also be vsplit)
  split = "myFile2",

  -- options local to buffer (mainFile)
  opts = {
    shiftwidth = 2,
    tabstop = 2
  },

  -- function to call inside mainFile's buffer
  callback = function()
    print("Ok")
  end
}

or

return {
  -- files to be opened in tabs
  tabs = {
    "myFile1",
    "myFile2",
    "myFile3",
    "myDir/*", -- can contain wildcards only if it's a string not wrapped by a table
    { "myDir/*" }, -- this will open the file named "myDir/*" if exists, not every file inside myDir

    {
      "myOtherFile",
      vsplit = {
        "mySplitFile",
        opts = { number = false }
      }
    }
  }
}

[!TIP] Each file inside the tabs group can be treated like the main one in the first snippet, with all options available.

Installation

Install it with your plugin manager of choice, just remember to call the setup function, otherwise it will not work. Lazy loading is not recommended since local-session.nvim needs to be active at the very beginning of the neovim start process.

Here is an example using lazy:

require("lazy").setup {
  ...,
  {
    "akmadan23/local-session.nvim",
    opts = {
      -- your configuration here (can be empty but do not omit it)
    }
  },
  ...
}

or pckr:

require("pckr").add {
  ...,
  {
    "akmadan23/local-session.nvim",
    config = function()
      require("local-session").setup {
        -- your configuration here
      }
    end
  },
  ...
}

Configuration

The plugin comes with the following defaults:

require("local-session").setup {
  filename = ".session.lua",    -- name of session files
  notify_session_loaded = true, -- if true a success notification will be displayed when a session file is loaded
}

Usage

Normal usage does not require any user interaction, just launch Neovim without file arguments in a directory containing a .session.lua file, and that will be automatically loaded.

Lua API

• local_session.load(path): loads the session file in the current directory or in path if specified.
• local_session.edit(): opens in the current buffer the session file in the working directory, if present.

[!NOTE] Assuming local_session = require("local-session").

Commands

• :LocalSessionLoad: alias for local_session.load()
• :LocalSessionEdit: alias for local_session.edit()