AutoSession for Neovim: automatic session restoration and branch-aware workflows

Why AutoSession targets per-project Neovim state

AutoSession addresses a narrow but common Neovim problem: reopening the editing context that existed when a particular project was last closed. According to the README, it automatically reopens files and windows when Neovim starts in a working directory that already has a saved session. When the directory has no session file, the plugin does nothing on startup. This makes the feature less intrusive for new projects while still allowing established projects to resume automatically.

The plugin is aimed at Neovim users who regularly move between directories and want to retain buffers and window layout rather than reconstructing it manually. Its scope is broader than one file list. The documented features include directory filtering, a session picker, directory-change tracking, Git branch-specific sessions, hooks, and custom data associated with a session. Those features make it relevant to users whose work is organized around several repositories or directories.

The basic model is directory-based. AutoSession looks for a session associated with the current `cwd`, restores it on startup when present, and saves a session on exit. With `auto_restore_last_session` enabled, it can also load the most recently saved session when there is no session for the current directory. That fallback changes the default behavior from strict project matching to a broader continuity model, so it should be treated as a deliberate choice rather than an incidental setting.

The project is not documented as a general-purpose workspace manager for arbitrary application state. Its documented state concerns Neovim sessions, buffers, windows, working directories, and optional custom data. The README does not claim that AutoSession preserves every external process, plugin state, or editor feature.

AutoSession’s directory, Git, and picker data flow

AutoSession stores sessions below `root_dir`, which defaults to `vim.fn.stdpath("data") .. "/sessions/"`. The default configuration enables automatic save, restore, and creation, while allowing users to suppress or restrict directories through `suppressed_dirs` and `allowed_dirs`. This gives the plugin a policy layer around the basic save-and-restore cycle. A session can be skipped for a directory considered unsuitable, while a newly created file can be allowed only when the relevant conditions permit it.

The naming layer can include a Git branch name by setting `git_use_branch_name = true`. That setting can also be a function accepting an optional path and returning the branch name. A second option, `git_auto_restore_on_branch_change`, can automatically restore the session when the Git branch changes, but the README states that it requires `git_use_branch_name`. This is useful for keeping separate work contexts on different branches, although it adds dependence on repository state and branch detection.

The session picker supports Telescope, Snacks, Fzf-Lua, and `vim.ui.select`. Pickers are detected automatically, and `session_lens.picker` can set one explicitly. For Telescope, `load_on_setup` registers the Telescope extension at startup so `:Telescope session-lens` can be used. `picker_opts` passes settings to Telescope, Snacks, or Fzf-Lua. If no supported picker is selected, the documented fallback is `vim.ui.select`.

Several settings affect what enters a session. `close_filetypes_on_save` defaults to `{ "checkhealth" }`, so buffers with that filetype are closed before saving. `close_unsupported_windows` defaults to true, while `preserve_filetypes` and `preserve_buftypes` can be used to keep selected unsupported windows. `preserve_buffer_on_restore` is a function that can decide whether a buffer should remain. These controls matter because automatic restoration can reproduce more than ordinary source-file windows.

Lazy.nvim installation and the first startup

The README documents installation through Lazy.nvim. The plugin specification sets `lazy = false`, so AutoSession is loaded as part of the configuration rather than waiting for a lazy-loading key event. The documented starting configuration also sets a list of suppressed directories and leaves `log_level` commented out. The setup call enables the plugin with the supplied options.

Add the following specification to the Lazy.nvim plugin configuration:

return {
  "rmagatti/auto-session",
  lazy = false,
  ---@module "auto-session"
  ---@type AutoSession.Config
  opts = {
    suppressed_dirs = { "~", "~/Projects", "~/Downloads", "/" },
    -- log_level = 'debug',
  },
}

After the plugin is installed and the configuration is loaded, start Neovim from a project directory. The README says AutoSession will restore the session for that `cwd` if one exists. On the next exit, it will automatically save the current session. A directory without an existing session produces no startup restore, and the plugin will create one when the default `auto_create` behavior permits it.

For plugin managers other than Lazy.nvim, the README gives a direct setup call:

require("auto-session").setup({})

That call is described as necessary somewhere in the configuration because setup must be invoked. The README does not document installation commands for a particular system package manager, nor does it specify a release artifact. There are no GitHub releases listed for the repository, so the repository configuration is the installation path described by the project.

Choosing directory, branch, and argument behavior

The default configuration does not automatically switch sessions when the working directory changes. That is controlled by `cwd_change_handling`. Enabling it allows AutoSession to save and restore sessions during directory changes. A separate `single_session_mode` keeps all work in one session regardless of directory changes, but the README explicitly says it does not work with `cwd_change_handling`.

The argument settings create another boundary around automatic behavior. With `args_allow_single_directory = true`, AutoSession follows its normal restore and save logic when Neovim is launched with a single directory as the only argument. Setting it to false skips auto-restore when any argument is passed. `args_allow_files_auto_save` controls whether saving is permitted when Neovim is launched with a file argument, or with multiple files or directories. It does not re-enable auto-restore.

For users who launch Neovim with explicit files, this distinction matters. A configuration may restore an existing session for the current directory while declining to save after a file-based launch. The README does not describe a fully transactional command sequence for migrating sessions between directories, and it does not document a separate restore command in the displayed documentation. A user who expects command-line file selection to be isolated from the saved workspace may need to test these settings with their normal launch patterns.

Symlinked paths are another source of variation. `resolve_symlinks` is false by default. Enabling it resolves symlinks in `cwd` and single-directory launch arguments before saving or restoring sessions. This can prevent two apparent paths from producing different session identities, but the README does not claim that all path forms are normalized beyond those two cases.

Hooks, extra data, and error recovery

AutoSession exposes two extension points for data beyond the normal Neovim session state. `save_extra_data` is a function that returns data to store with the session, and `restore_extra_data` is called when that saved data is available. The README does not define a serialization format or schema for this field, so the implementation of these functions must follow the plugin’s own expectations and Neovim session handling rather than assuming a portable data format.

Restore failures have separate controls. `restore_error_handler` can be replaced with a function called when restoration produces an error. By default, the plugin ignores fold and help errors, while other errors are displayed and cause auto-save to be disabled. The default handler can be accessed through `require('auto-session').default_restore_error_handler`. `continue_restore_on_error` defaults to true, allowing loading to continue after an error. Those settings provide a way to choose between preserving the partial restore and stopping further behavior.

The plugin can also stop language servers during restoration through `lsp_stop_on_restore`. The value can be a boolean or a function. The README specifically states that this callback is not called for startup auto-restore. This distinction can matter to users who expect hook-like behavior to be identical during startup and later restores.

`save_and_restore_shada` defaults to false. When enabled, it stores and restores ShaDa data such as command-line and search history, registers, marks, and global variables, and requires Neovim 0.11 or newer. This broadens the persisted state and therefore deserves deliberate review before being turned on.

Filtering, cleanup, and session deletion costs

Automatic session creation brings a storage and cleanup responsibility. By default, `auto_delete_empty_sessions` is true, and AutoSession deletes a session when auto-saving leaves only unnamed or empty buffers. That avoids retaining files that represent no useful workspace, but users who intentionally keep empty buffers may need to account for this behavior.

A second maintenance mechanism is `purge_after_minutes`. It is disabled by default. The README states that sessions older than the configured number of minutes are deleted asynchronously on startup, with the example value `14400` representing ten days. This option requires Neovim 0.10 or newer. Because deletion happens during startup, the exact session access and scheduling behavior should be checked against the project’s current documentation before relying on it in a long-lived setup.

The repository is not archived, and its last push was on 2026-09-22. No GitHub releases are listed, which means the repository does not provide a release-based upgrade schedule. The maintenance work visible in the repository includes tests, workflow configuration, and a Makefile, but the README does not promise compatibility across every Neovim release. The default settings include several version-dependent features, so upgrades should be checked against the Neovim version used by the editor.

The project is MIT licensed. That identifies the repository’s stated license, but it does not remove the need to review how a user’s session data, ShaDa content, extra data, and generated files are handled on the machine where the plugin runs.

AutoSession compared with manual Neovim session commands

The closest practical alternative is managing Neovim’s built-in session behavior manually. Manual use gives the editor user direct control over when a session is written and loaded, with no automatic directory-based restore on startup and no separate session file created simply because a matching directory was opened. The cost is that restoring buffers, windows, and project context becomes an explicit action instead of an automatic one.

AutoSession differs by adding policy and integration around that basic mechanism. It stores sessions under a configurable root, filters directories, can name sessions by Git branch, provides picker integrations, tracks directory changes, supports hooks and extra data, and can clean up old sessions. Manual session management may be preferable when automatic restore causes unexpected workspace reconstruction or when the user needs to control every invocation.

The choice is therefore not simply between saving and not saving. It is between explicit session commands and a directory-aware automation layer. AutoSession is more useful for users who repeatedly switch among projects and accept automatic behavior. Manual control is more predictable for users who open Neovim with carefully selected files, inspect each session, or need a narrower persistence boundary.

Editorial conclusion

AutoSession fits Neovim users who want their buffers and windows restored per working directory, especially those working across Git branches. It is a poor fit for users who want no automatic persistence or who cannot tolerate session restore and cleanup behavior without reviewing their filters, root directory, and supported window types. Verify first that your preferred picker is installed, that your Neovim version supports any optional configuration, and that the chosen `root_dir` is appropriate for the files and projects it will manage.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. rmagatti/auto-session on GitHub