obsession.vim: session files that keep themselves up to date

The problem with :mksession is the timing

Vim ships with a `:mksession` command that writes a file containing the current state of Vim: window positions, open folds, stuff like that. That part is fine. The part that is not fine, in the author's words, is the interface, which for most of his existence was too awkward and manual to be useful.

The awkwardness is a scheduling problem. A session file is a snapshot, and a snapshot is only correct at the moment it is taken. The natural moment is immediately before quitting Vim, and the natural user behaviour is to forget. So the user ends up with either a session that is ten minutes out of date or no session at all.

The plugin's approach is to stop asking the user to be present at the right moment, and to re-capture often enough that the file is never far from the truth. The documentation describes it as continuously updated session files, and the repository description is shorter still.

The scope is worth stating precisely, because it is narrow. What is captured is Vim's own state: the windows, the layout, the folds, the buffer list and the working directory. What is not captured is the wider working environment. A session file does not restore your terminal emulator, it does not restore a set of plugins, it does not remember which shell you had open in a particular directory beyond the working directory Vim itself keeps, and it does not bring back the panes of a multiplexer.

That is not a criticism of the plugin, it is the scope of `:mksession`, and the plugin's achievement is that it makes a Vim feature work as a user expects it to.

Five tweaks, and every one of them is about timing

The README lists the changes as a small set of tweaks, and reading them together is the clearest description of the plugin.

The first is that instead of making the user remember to capture the session immediately before exiting Vim, it is allowed to capture at any time, and `:mksession` is re-invoked automatically immediately before exit.

The second is that `:mksession` is also invoked whenever the layout changes, in particular on `BufEnter`, so that even if Vim exits abnormally the session is good to go. That single detail is what makes the plugin worth installing, because an abnormal exit is exactly the case where a manually saved session is most valuable and least likely to exist.

The third is that loading an existing session automatically keeps it updated in the same way. So a session file is not a thing you restore once, it is a live file that follows the session you are working in.

The fourth is about friction. If the user tries to create a new session on top of an existing one, it does not refuse to overwrite it, it just does what is meant. There is no confirmation prompt and no error, and that is a deliberate choice about how much ceremony a status bar feature should have.

The fifth is about paths. If a directory is passed rather than a file name, it creates a `Session.vim` inside of it. That is the behaviour that makes the plugin usable per project, since a directory is the unit a person thinks in and a file name inside it is the unit the session format needs.

So four of the five tweaks are about the same problem, which is that a snapshot is stale, and the fifth and fourth are about removing friction from the commands.

Why options and maps are deliberately left out

One decision deserves a section of its own, because it looks like a limitation and is actually the design.

The plugin does not capture options and maps. The reason given is that options are sometimes mutilated and maps just interfere with updating plugins.

Both halves of that are worth unpacking. A session file that restores options restores the options as they were when the session was recorded, which for a user whose configuration has changed since is a way to reintroduce old settings, and options are global to Vim, so a stale option in a restored session can change behaviour in a way the user did not expect. And key mappings, in a modern Vim with a plugin manager, are usually generated by the plugins themselves at start-up, so a recorded map is a duplicate of a map the plugin is about to define, and the two fight.

So the plugin deliberately narrows the session to the parts of the state that are the user's own and that a plugin cannot regenerate: where the windows are, what is folded, which buffers are loaded, which directory is current. Everything that a plugin or a configuration file is responsible for is left alone, and the user's own files remain the source of truth for that.

That is a design decision that a lot of session plugins do not make, and it is a reminder that the session format was designed for a Vim that did not have plugin managers, and that using it today means deciding which of the original contents still belong to the user.

The commands, the indicator and the help file

The user interface is deliberately small.

`:Obsess` with an optional file or directory name starts recording to a session file, and `:Obsess!` stops and throws it away. That is the whole of it, and a session is then loaded in the usual manner, either with `vim -S` or with `:source`.

There is one more piece, and it is the part that makes the feature visible rather than invisible. There is an indicator that can be put in the `'statusline'`, the `'tabline'` or the `'titlestring'`, and it is documented separately under `:help obsession-status`. A status line indicator for a feature that is otherwise completely transparent is a good idea, because the only failure mode of an automatic feature is that the user forgets it is running and wonders why a file is being written.

The help documentation is part of the repository, in a `doc/` directory, and it has to be generated before it can be read, because Vim does not read help tags from a plugin directory until the tags are built. That is why the installation instructions include a command that generates them rather than just telling you to clone the repository.

The repository is small and conventional for a Vim plugin. There is a `plugin/` directory with the code, a `doc/` directory with the help file, a `README.markdown` and a `CONTRIBUTING.markdown`, and a `.github/` directory for the continuous integration.

The project is also distributed through the Vim script site, with the script page at vim.org for script number 4472, and the README asks readers to follow the repository and vote for it there. The plugin is written in Vim Script, the default branch is `master`, and the last push was on 2026-09-20.

Installing it with pathogen and generating the help tags

The installation is a clone and a command, and it assumes pathogen as the plugin manager, which the README recommends if you do not have a preferred method.

cd ~/.vim/bundle
git clone https://github.com/tpope/vim-obsession.git
vim -u NONE -c "helptags vim-obsession/doc" -c q

The three lines do three things. The first moves into the directory where pathogen keeps the plugins, the second clones the repository into a `vim-obsession` directory, and the third generates the help tags for the `doc` directory so that `:help obsession-status` works.

That last line is the step that people skip, and skipping it produces a plugin that appears to do nothing, because the help is the only user interface beyond the two commands. The `-u NONE` part starts Vim without loading your configuration, which matters because the command has to work before the plugin is installed, and the `-c q` quits afterwards so the command does not leave a Vim instance open.

The `~/.vim/bundle` path is pathogen's convention, so somebody using a different plugin manager has to translate the first line, but the rest works unchanged.

There is no package manager entry, no dependency and nothing to compile. The plugin is Vim Script, and the whole of the install is a directory in the right place and a help tag file.

The licence is Vim's own, and that is the point

The licence section is two lines and they matter.

Copyright Tim Pope. Distributed under the same terms as Vim itself. See `:help license`.

That is not a licence identifier, it is a pointer, and the pointer is the point. Vim's own terms are a copyleft licence for the editor, and a plugin that ships as part of the same ecosystem under the same terms is a deliberate choice by the author to keep the plugin and the editor in the same legal family. The consequence for a user is that `:help license` inside Vim is the authoritative text, and for a distributor it is that the terms travel with Vim rather than being negotiated separately for this plugin.

The GitHub metadata does not classify the licence under a standard identifier, which is why the README points at Vim's documentation rather than at a file in the repository. There is no `LICENSE` file in the root listing, and the terms live where the project says they do.

For an evaluation this is a small point that a checklist would miss. A plugin that is distributed under the same terms as the editor it extends is the most predictable outcome for a company that already ships Vim in its image, and a project with its own permissive licence would be the one to ask about.

Where obsession.vim is the wrong tool

The limits are the limits of the underlying feature, and they are worth being concrete about.

The first is scope. A session file is a window layout. It does not restore a terminal multiplexer, it does not restore a set of open shells, it does not restore your plugins, and it does not restore the state of a terminal emulator. A user who wants to come back to a workspace with four shells, an editor and a database client is asking for a session manager, and this is not one.

The second is the overwrite behaviour. The plugin is explicitly designed to replace a session file without asking, because the author wanted no friction. That is the right default for a status line feature and the wrong default for a file somebody cares about, so a user with a session they hand wrote, or one another tool consumes, should know that recording over it is a single command away.

The third is that the feature is invisible in the way a transparent feature is. A status line indicator exists, and it can be put in the statusline, the tabline or the titlestring, but a user who has never read the documentation may not know that their Vim is writing a file on every buffer change, and a user who has installed the plugin by accident may not know how to stop it beyond `:Obsess!`.

The alternative, for a user who wants the layout restored and nothing more, is to run `:mksession` by hand and learn where the file went, which is the workflow this plugin was written to make unnecessary. The difference in approach is that obsession.vim moves the session from a command you remember to a file that maintains itself, and for somebody whose context is scattered across a dozen projects that is the difference between a feature you use and a feature you forget about.

Editorial conclusion

obsession.vim fits a Vim user who works in several projects at once, who moves between buffers and directories constantly, and who has given up on remembering to save a session before quitting. It is the wrong tool for somebody who wants a project workspace rather than a window layout, because the session captures Vim's state and nothing else, and it is the wrong choice for somebody who expects the session to restore a terminal, a working directory per window or a set of plugins, since none of that is what a session file contains. Before installing it, read the licence note, because the distribution terms are Vim's own rather than a standard software licence, and decide whether you want the automatic overwrite behaviour, since the plugin is explicitly designed to replace a session file without asking.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. tpope/vim-obsession on GitHub