garbage-day.nvim stops your LSP clients when Neovim loses focus

The problem: background language servers that will not let go

The stated motivation is specific. In many scenarios, unmanaged LSP clients running in the background can take several gigabytes of RAM, and the author wrote this collector to free that memory automatically, originally for NormalNvim, though the README says you can use it on any distribution. That framing matters because the plugin is not trying to make your editor faster. It is trying to make your editor smaller when you are not looking at it. Language servers are long-lived processes, and the default behaviour in most editors is to keep them alive for the whole session so that the next file of the same type opens instantly. The trade the plugin makes is deliberate: give up some of that instant-warm advantage in exchange for memory that comes back when you leave. The topics confirm the scope, with language-server-protocol, neovim-plugin, nvim-lsp and nvim-plugins, and the primary language is Lua with the repository not archived and the last push on 2026-08-19.

Installing it through lazy.nvim

The setup section gives one configuration block, and it is a lazy.nvim plugin spec with an event of VeryLazy so that the plugin itself does not cost you anything at startup.

{
  "zeioth/garbage-day.nvim",
  event = "VeryLazy",
  opts = {
    -- your options here
  }
},

The plugin also supports changing options at execution time, with the README giving the form of that as setting a key on the g:garbage_day_config table from a command line, so you can adjust the grace period or toggle a mode without editing your configuration and reloading. The repository layout is small and tells you how the code is organised: a lua directory with the plugin code, a selene.toml and a .selene-schema.yml for the Lua linter, a .stylua.toml for formatting, a .github directory, a LICENSE and the README. Releases are v1.4.0 from 2026-02-25, v1.3.1 from 2024-09-23 and v1.3.0 from 2024-05-23.

The four options that decide when servers die

The available options table is short, and the defaults tell you the intended behaviour. aggressive_mode defaults to false, and setting it to true stops all LSP clients except the current buffer every time you enter a buffer. The README is precise about two things: aggressive_mode ignores grace_period, and it only triggers when you enter a buffer with a different filetype than the current buffer. That last condition is the interesting design choice, because it means the aggressive path only fires when you are actually switching languages, not every time you move between two files of the same type. The stated purpose is maximum RAM saving. excluded_lsp_clients is a table of clients that should never be stopped, described as useful for LSP clients that misbehave, with the default table living in the plugin's config module. grace_period defaults to 60*15, the number of seconds to wait before stopping all LSP clients after Neovim loses focus. And wakeup_delay defaults to 0, the milliseconds to wait before restoring LSP after the mouse re-enters Neovim, offered as a way to avoid waking clients by accident when the mouse passes over the window.

The debug options, and the one rule you must not break

There is a separate set of debug options for the case where a particular client does not start or stop correctly on your machine. aggressive_mode_ignore is a list of buffers to ignore when aggressive_mode fires, and notifications defaults to false and when set to true gives you a notification every time garbage collection triggers, which is the first thing to turn on when something is not behaving. retries defaults to 3, the number of times to try to start an LSP client before giving up, and timeout defaults to 1000 milliseconds, the time taken for the retries to complete, with the README's example that by default it tries 3 retries for 1000ms. Below the tables there is an instruction that matters more than the individual defaults: if you change the default values, make sure the value of grace_period is always bigger than timeout/1000. The reason given is that this leaves enough time between stop_lsp() and start_lsp() so that they do not overlap, which is the kind of detail that turns into a race condition with no useful error message when it is wrong.

Triggering collection by hand from a keymap

The FAQ answers the question of whether garbage collection can be triggered manually, and it can, through the plugin's utils module.

require("garbage-day.utils").stop_lsp()  -- stop all lsp clients.
require("garbage-day.utils").start_lsp() -- start lsp clients for the current buffer.

The two calls are deliberately separate, so you can bind them to different keys, one to free memory on demand and one to warm the servers back up. That makes the plugin usable as a building block in a larger workflow rather than only as an automatic background behaviour, which is the more useful of the two modes if you know when you are about to switch projects. The FAQ also records the tested Neovim versions, 0.10, 0.11, 0.12 and 0.13, and asks that anyone on a newer version who finds it not working open an issue, since the plugin uses LSP client APIs that have changed across those releases.

Where garbage-day.nvim is the wrong choice

Three limits. The first is that it trades startup latency for memory, and for some people that trade is the wrong way round. If you keep four language servers for four languages open and switch between projects all day, every switch back now costs you a server start, and the aggressive mode makes that worse by firing on every filetype change rather than only on focus loss. Whether that is acceptable depends on your machine and how often you switch, and the plugin cannot decide that for you. The second is that stopping a client is not always clean. The README itself anticipates clients that misbehave and ships excluded_lsp_clients for them, which tells you the author has seen clients that fail to restart or fail to shut down properly. Any client you exclude is a client whose memory is never reclaimed, so the exclusion list is a direct subtraction from the benefit. The third is the alternative the README points at, lsp-timeout, which is recommended for Neovim versions at or below 0.8. That is a different mechanism with a different design, and the recommendation is specific: for older versions, use lsp-timeout rather than this plugin. On a current Neovim the choice is narrower, but it is still a choice between a background collector that acts on focus and a timeout-based one that acts on idleness, and they will not behave the same way on your setup.

Editorial conclusion

Adopt garbage-day.nvim if your Neovim setup holds several language servers open at once and you see the memory cost when you switch away from the editor. Skip it if you work in one language at a time or if your servers are cheap to keep warm. Before you change any defaults, remember the README's constraint that grace_period must stay larger than timeout divided by 1000, so the stop and start calls cannot overlap.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. Zeioth/garbage-day.nvim on GitHub