satellite.nvim: a scrollbar that shows what is in your buffer

The problem it solves, stated in one line

satellite.nvim is a Neovim plugin that displays decorated scrollbars. That is the whole feature, and the word decorated is where the value is.

A standard scrollbar tells you where you are in a file. It is a position indicator and nothing more. A decorated scrollbar also tells you what is in the file: where the errors are, which lines have uncommitted changes, where your last search matched, where the quickfix entries sit.

The feature list names the built-in handlers, and they cover the things a Neovim user already has floating around a buffer. Cursor. Search results. Diagnostic. Git hunks, via gitsigns.nvim. Marks. Quickfix. There is also handling for folds, and mouse support, so the scrollbar is not a decoration you cannot click.

The plugin is enabled by default once installed, and the configuration is optional. The three commands are SatelliteDisable to turn the scrollbars off, SatelliteEnable to turn them back on, which is only necessary if they have previously been disabled, and SatelliteRefresh to redraw them when they have drifted out of sync, which the README says can occur as a result of some window arrangement actions.

That last command is worth noting. The existence of a refresh command for a scrollbar tells you the scrollbar is derived state, and derived state sometimes goes stale. It is a small thing, and it is the kind of small thing that separates a plugin that works in practice from one that works in the author's setup.

The plugin is based on nvim-scrollview, which the README credits for providing a very good implementation for a normal scrollbar, and it lists nvim-scrollview and nvim-scrollbar as similar plugins.

The candid warning, which tells you more than the feature list

There is a note near the top of the README that deserves to be quoted rather than paraphrased, because it is the honest characterisation of the project.

Many APIs required to implement a decorated scrollbar in Neovim do not yet exist, and because of this, this plugin implements fairly unideal and unoptimised workarounds to get desired behaviours.

That is the author telling you that the plugin does what it does by working around gaps in the editor's API rather than by using a supported mechanism. The consequences are predictable. Performance is not the concern it could be, because the workarounds are unoptimised. Behaviour in unusual window arrangements can be wrong, which is exactly what the SatelliteRefresh command exists for. And the plugin is tied to whatever nightly features it depends on, which is why the requirement is Neovim nightly rather than a released version.

The requirement is stated flatly: Neovim nightly. There is no compatibility matrix and no fallback to a stable release, which is an honest constraint for a plugin that depends on unreleased APIs.

So the evaluation is a straight trade. If you want a rich visual map of a buffer and you already run nightly, the plugin gives you one that no other plugin in the list provides. If you want something with predictable performance and no API risk, a plain scrollbar plugin is the better answer.

The maintenance picture adds context. The last push to the repository was on 2026-05-01 and the only release is v1.0.0 from 2023-07-05. So the code is still being worked on, and the version number has not moved in three years, which is consistent with a plugin whose upstream dependencies are still shifting.

The configuration surface, and what the defaults reveal

The setup function takes a table, and the example in the README shows most of the default settings, which is a good way to see the design.

require('satellite').setup {
  current_only = false,
  winblend = 50,
  zindex = 40,
  excluded_filetypes = {},
  width = 2,

The first group is about the scrollbar itself. width is 2, so the scrollbar occupies two columns. winblend is 50, the transparency of the scrollbar window, and zindex is 40, the stacking order relative to other floating windows. current_only defaults to false, and when true the scrollbar would show only the current window's marks rather than the whole buffer. excluded_filetypes is empty by default, which means the scrollbar appears in every buffer, and that list is where you would exclude filetypes where a scrollbar makes no sense, such as a very short scratch buffer.

The handlers block is the interesting part, because it shows the plugin is a set of independent sources rather than a monolithic decoration. The cursor handler has a symbols list, and the comment says it supports any number of symbols, with an alternative two-symbol list commented out. The four default symbols are the little arrow characters that indicate whether the cursor is above, at or below the visible area.

The search handler has no options beyond enable and its highlights. The diagnostic handler has signs, a three character set, and a min_severity that defaults to the HINT level, which means by default the scrollbar marks every diagnostic including hints, and you can raise that threshold.

The gitsigns handler maps to the sign characters of the gitsigns plugin, with a comment noting the sign can only be a single character, though multibyte is acceptable. The marks handler has a show_builtins option for the builtin marks like [ ] < >, and a key of m that is the mark it represents. The quickfix handler has its own sign set and its own highlight.

Highlights that follow the editor, and the folding of the colour scheme into the design

One detail runs through the whole configuration and is easy to miss: every handler has highlights, and each one defaults to a link to an existing highlight group.

The cursor handler uses SatelliteCursor, which defaults to a link to NonText. The search handler uses SatelliteSearch, defaulting to Search, and SatelliteSearchCurrent, defaulting to SearchCurrent. The diagnostic handler has four, one for each severity, defaulting to DiagnosticError, DiagnosticWarn, DiagnosticInfo and DiagnosticHint. The gitsigns handler has SatelliteGitSignsAdd, SatelliteGitSignsChange and SatelliteGitSignsDelete, defaulting to the equivalent gitsigns groups. The marks handler uses SatelliteMark, defaulting to Normal, and the quickfix handler uses SatelliteQuickfix, defaulting to WarningMsg.

So out of the box the scrollbar inherits the colours of whatever the rest of your editor is showing, which is the right default and means the plugin does not fight your colourscheme on day one. The corollary is that if you override a highlight group, the scrollbar follows it, and if you want the scrollbar to look different you have to link its group explicitly.

The marks handler is a good example of the plugin following the ecosystem rather than reinventing it. The gitsigns handler does not reimplement git change detection, it reads what gitsigns already computed and maps the add, change and delete signs to characters in the scrollbar. The diagnostics handler does the same with the diagnostic API, including the severity threshold.

That pattern is why the plugin needs no git or diagnostic code of its own, and it is also why the diagnostic and quickfix handlers look so similar in configuration: they are the same mechanism applied to two different sources of information.

The handler API, and how you would add a mark of your own

Satellite provides an API to implement handlers for the scrollbar, and the details live in a HANDLERS.md file at the repository root.

That is the extension point that turns this from a fixed decoration into a framework. The built-in handlers cover cursor, search, diagnostics, gitsigns, marks and quickfix, but the plugin is designed so that something else can register marks too. For a plugin that shows what is in a buffer, the natural next handler is something the plugin does not know about, and the API exists so that adding one does not require patching the plugin.

The repository layout is small and tells you where things live. There is a lua/ directory for the plugin code and a plugin/ directory for the Neovim plugin file that sets up the commands. There is a doc/ directory, which is what backs the :help satellite command, and the README says documentation can be accessed with that command. HANDLERS.md sits at the root as the developer-facing document.

The tooling is a single Makefile whose default goal is to run StyLua, and the way it fetches the formatter is worth a glance. It detects Darwin and Linux, maps that to a StyLua platform, downloads a pinned StyLua v0.18.2 release zip from the upstream GitHub releases URL with wget, and unzips it. There are two targets, stylua-check which runs the check mode over the lua directory and stylua-run which formats it in place. The check target is what a continuous integration job would run.

The linting and language server configuration are there too, with a .luacheckrc for luacheck and a .luarc.json for the Lua language server, plus a .stylua.toml for the formatter settings and an .emmyrc.json for EmmyLua. A Neovim plugin that is this small still has four separate tool configurations, which says something about the standard the author holds.

Editorial conclusion

Adopt satellite.nvim if you want a visual map of a long buffer, particularly if you work with diagnostics, git changes or search results and lose track of where they are in a large file. Do not adopt it if you are on a stable Neovim release, because the requirement is Neovim nightly, and be aware that the author describes the implementation as unideal and unoptimised workarounds. Before you install it, check that the plugin's own highlights do not fight your colourscheme, and read the HANDLERS.md API if you want to add your own kind of mark rather than only enabling the built-in ones.

Frequently asked questions

Official sources

1. Issues
2. lewis6991/satellite.nvim on GitHub
3. License: MIT
4. README
5. Releases