nixCats: a Nix category system for Neovim plugins, now in maintenance mode

The repository says it is superseded, and that changes what it is for

nixCats is for the Lua-natic's Neovim config on Nix, and the first thing the README says is that this repository is in maintenance mode, with a pointer to a different project.

The successor is the neovim wrapper in nix-wrapper-modules, and there is a kickstart.nvim style template for it. The core nix code of nixCats that makes the project run will continue to work, and the actual wrapping of neovim works in a very similar way, so the author says maintenance changes can be mirrored here and he anticipates very few of them.

Then comes the honest warning about templates. If a template becomes too much to maintain, I may simply delete it instead, and the author notes that he already did this with one of them.

That is a detail worth taking seriously, because a template is the thing most people actually consume. If you are reading this to decide whether to build on nixCats, the answer is that the successor is where the new work is and where a template will exist.

The stated reason for the move is that the author made something better enough to warrant it. nix-wrapper-modules brings the same level of control to every program using the module system, rather than to one program, and the docs page for the neovim wrapper is linked from the README.

The two projects are not equivalent in shape, though, and that difference is the substance of the rest of this article. nixCats is a category system, and the new one is a module with specs.

The philosophy: install with Nix, configure with Lua

The introduction states the goal plainly. The goal of nixCats is to make it as easy as possible to interact with the normal configuration scheme, while using Nix to install things and add useful meta-features. This is the opposite approach to projects like nixvim or nvf, which aim to nixify Neovim as much as possible.

The end result is comparable to, if not better than, using a regular Neovim package manager plus Mason, and the README says it is much more portable.

The reasoning behind that choice is about maintenance cost rather than about style. The Neovim plugin ecosystem is very large and updates are often, and a design that nixifies every plugin spends a lot of time maintaining simple translations of Lua options into Nix, or worse, lags behind on new features because the translation has to be reapplied for each plugin.

So nixCats aims for a higher quality experience interacting with the plugin ecosystem as it is, and it only needs a single Nix file to effectively manage your Neovim installation. You also still get the usual nice features and Lua autocompletion.

The gap this fills is the one the README calls out with a question. What if you want to pass information from Nix to the rest of your Neovim configuration? That is where Home Manager and pkgs.wrapNeovim start to fall short. It is not uncommon to see a mess of global variables written in Nix strings, and a bunch of files called via dofile that are not properly detected by Neovim tooling. To pass info from Nix to Lua you must interpolate a string, which means writing Lua inside a Nix string, which is the thing tooling cannot follow.

The category scheme is the answer, and it has three steps. Make a new list in the correct section of categoryDefinitions, for example a list in the startupPlugins set for plugins that load on startup. Enable that category for the desired Neovim package in packageDefinitions. Then check for it in your Neovim Lua conf.

Categories, and the problem of the plugin ecosystem's size

The category system is the mechanism, and the reason it exists is stated in the introduction as avoiding a specific trap. It avoids falling into the trap of trying to make a module for every plugin somebody might want to use, because the plugin ecosystem is very large and updates are often, and that leads to a lot of time spent maintaining simple translations of Lua options into Nix.

A category is a named set of plugins, defined in Nix, which the Lua side then queries. The Lua configuration does not need to know the plugin's path, its version or its dependencies, because the category tells it which set of plugins is enabled and the build has already placed them where they belong.

The reference in the guide is nixcats.org/nixCats_format.html for the categoryDefinitions and packageDefinitions outputs of the flake, which tells you these are flake outputs rather than internal implementation details, and therefore something a user is expected to write.

The site also has a Table of Contents at nixcats.org/TOC.html, and the README's own table of contents lists an Introduction, a Getting Started and a Special Mentions section, so the bulk of the documentation lives on the site rather than in the repository.

The repository layout matches that split. There is a default.nix and a flake.nix at the root, a builder/ directory for the build logic, a templates/ directory for the starting points, a nixCatsHelp/ directory, utils/ and tests/ directories, plus a CHANGELOG.md, a CONTRIBUTING.md and a LICENSE.

The templates/ directory is the part under the deletion threat, and it is where a new user would look first. A template that disappears mid-project is not a small inconvenience, so the practical advice for anyone starting now is to copy what you need rather than track the branch.

The lazy.nvim section, and a candid warning about it

The README has a long section on lazy.nvim, and its purpose is to steer people away from the tool the templates once shipped with, rather than to help them adopt it.

The note says that if someone wants to adapt the nixCatsUtils/lazyCat.lua file to work with the new wrapper, it would be a simple task. The file simply sets some lazy.nvim options to treat the nix-provided plugins as dev dependencies, and the info plugin in the new wrapper contains the plugin paths just like it does here. If you do this, feel free to post about it in discussions on the new repository.

Then the reason the file exists at all is given. This repository only ever contained such a file because it predates both lze and lz.n. They work well with both the built-in Neovim plugin manager and with nix-provided plugins. They have been around long enough to prove that they are actually a better alternative, at least for this use case if not others.

So the recommendation is explicit: use lze or lz.n instead. Using lazy.nvim is not the best way to do lazy loading with any nix wrapper scheme, despite the workarounds.

For anyone who decides to use lazy.nvim anyway, the settings are given precisely, and they are the kind of detail that would otherwise take an afternoon to work out. dev.path can receive a function that receives the spec and should return the path to the plugin. dev.patterns is set to an empty string set, or you fetch the names you downloaded from nix from the info plugin. dev.fallback = true lets it still fall back to downloading via lazy.nvim in that case. performance.rtp.reset = false and performance.reset_packpath = false.

And then the consistency requirement, which is the part that would bite. You have to make sure all names detected by lazy.nvim agree with their nix counterpart via that spec's name field, or make sure the name from nix agrees with the one from lazy.nvim by setting pname for that plugin. When the two managers disagree about a plugin's name, the plugin is loaded twice or not at all, and the error message points at the wrong thing.

What carried over to the new wrapper, and what improved

The comparison with the successor is the most useful part of the README for anyone deciding where to start.

The category system becomes specs. The neovim module takes flexible specs that you can add type-safe options to with the module system, and they can be used in a similar fashion to the categories, but also in a lot of new ways. The Lua tips and tricks used in the templates here are all applicable there.

The information plugin carries over too, with a lot of the same information in it. Just like nixCats, the new approach allows you to split things up into groups and inform your Lua of that, and it is still possible to install multiple neovim executables at once should that be desired.

The improvement the author emphasises is overriding. The ability to override your configuration later is much improved. You can make your own module options, and then you override it later the same way you configured it in the first place, simply by providing another module.

That is a real difference in mechanism. In the category model, overriding a category means editing a list in categoryDefinitions, which means editing the flake output and rebuilding. In the module model, an override is another module in the same list, so the composition rules handle the precedence, and the type-safe options the module system provides catch the mistakes that the category model leaves you to discover at build time.

The author is also candid about the cost of the switch. nixCats theoretically has a lot of capabilities, and you will find them all there as well, and will likely have an easier time actually making use of them. Which is a different kind of admission, from someone who built the thing, and it is the argument for moving rather than the argument for staying.

Maintenance status, licence and what to actually do with this repository

The maintenance facts are simple. The last push was on 2026-09-14, the repository is not archived, and the most recent releases are v7.3.6 on 2026-01-20, v7.3.5 on 2026-01-16 and v7.3.4 on 2026-01-05. So the repository is being maintained in the sense that the core still works, and the version numbering says the author was still shipping releases in January 2026.

The licence is MIT, and the repository has a LICENSE file at the root alongside a CHANGELOG.md and a CONTRIBUTING.md, so it is a normal open source project in its paperwork.

The description of the repository as the predecessor to the neovim wrapper module in nix-wrapper-modules tells you the relationship, and the homepage is nixcats.org.

So what should you do with it, concretely. If you are starting a Neovim configuration now, use the wrapper module in nix-wrapper-modules, because the author says it can do everything nixCats can, the Lua tips carry over, the grouping concept survives as specs, and the override story is better. If you already have a working nixCats configuration, the core nix code will continue to work, and you can migrate on your own schedule, with the caveat that you should copy any template you rely on rather than tracking the branch.

If you want to understand the design rather than use it, this repository is still worth reading, because the category scheme is a clean answer to a problem that most Nix Neovim wrappers have: how do you let Nix own the installation and the plugin set while leaving the configuration in the language the editor's tooling understands. That problem has not gone away just because this particular solution has been superseded.

Editorial conclusion

Adopt nix-wrapper-modules' neovim wrapper instead of nixCats if you are starting a Neovim configuration today, because the author says the new wrapper can do everything this one can and opens up more possibilities while reducing interface complexity. Do not start a new project on nixCats itself, since the repository is in maintenance mode and the author warns that a template may simply be deleted if it becomes too much work. If you already use it, the core Nix code will continue to work and the advice is to migrate when the wrapper suits you.

Frequently asked questions

Official sources

1. BirdeeHub/nixCats-nvim on GitHub
2. License: MIT
3. Project website
4. README
5. Releases