A Neovim color scheme plugin that automatically syncs with caelestia-shell and reloads in real-time when your theme changes. Keep your editor in perfect harmony with your desktop environment.
demo.mp4
- Automatic synchronization - Reads color scheme directly from caelestia-shell
- Real-time reloading - Automatically updates when you change themes in caelestia-shell
- Material Design 3 tokens - Uses modern color system for consistent theming
- LazyVim compatible - Works seamlessly with LazyVim (but not required)
- Cross-distro support - Primarily designed for Arch Linux with Hyprland, but works on other distributions
- Neovim (version 0.7+ recommended for file watching support)
- caelestia-shell installed and configured
- File system event support (provided by Neovim's libuv integration)
- Clone this repository to your Neovim configuration directory:
git clone https://github.com/yourusername/caelestia-nvim ~/.config/nvim/caelestia-nvim- Add the plugin to your Neovim configuration (
~/.config/nvim/init.luaor~/.config/nvim/init.vim):
For Lua configuration:
vim.opt.runtimepath:prepend("~/.config/nvim/caelestia-nvim")
require("caelestia").setup()For Vimscript configuration:
set runtimepath^=~/.config/nvim/caelestia-nvim
lua require("caelestia").setup()Alternatively, if you're using a plugin manager structure, you can clone it to your plugins directory and add it to your runtimepath accordingly.
caelestia-nvim reads the color scheme from caelestia-shell's state file located at $XDG_STATE_HOME/caelestia/scheme.json (defaults to ~/.local/state/caelestia/scheme.json if XDG_STATE_HOME is not set).
The plugin uses Neovim's built-in file system watcher (vim.loop.new_fs_event()) to monitor this file for changes. When caelestia-shell updates the theme, the plugin automatically:
- Detects the file change
- Reads the new color scheme
- Applies the colors to Neovim's highlight groups
- Notifies you that the theme has been reloaded
All color values are automatically formatted with the # prefix required by Neovim's highlight system.
The plugin works out of the box with no configuration required. Simply call require("caelestia").setup() in your Neovim configuration.
The setup function:
- Applies the current color scheme on startup
- Starts watching the scheme file for changes
- Automatically reloads when changes are detected
This means caelestia-shell hasn't generated the scheme file yet, or it's located in a different path. Ensure:
- caelestia-shell is installed and has been run at least once
- The scheme file exists at
$XDG_STATE_HOME/caelestia/scheme.jsonor~/.local/state/caelestia/scheme.json - You have read permissions for the file
If the theme doesn't reload when you change it in caelestia-shell:
- Check that file watching is supported on your system (most modern systems support this)
- Verify the scheme file path is correct
- Try manually reloading with
:lua require("caelestia").apply_colors()
If you see errors about file watching:
- Ensure you're using Neovim 0.7 or later
- Check that the scheme file path is valid and accessible
- Verify your system supports file system events (Linux, macOS, and Windows all support this)
MIT License
Copyright (c) 2024
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.