LazyVim configuration

Personal, Linux-first Neovim configuration built on LazyVim. It provides a modern IDE setup while keeping the repository's custom Cyberdream theme, statusline, and <leader>tt theme toggle. Dependency bootstrap also supports macOS and native Windows.

Supported baseline

• Neovim 0.12.4 or newer in the 0.12 release line, built with LuaJIT
• LazyVim 16.x
• lazy.nvim 11.17.x
• Linux as the primary runtime; macOS and native Windows bootstrap adapters

Plugin releases are not selected by semantic-version tags. LazyVim recommends following compatible upstream commits because many Neovim plugins publish stale tags. lazy-lock.json records the exact reviewed snapshot used by this configuration.

Requirements

The repository includes a cross-platform bootstrap installer. Preview it first:

# Linux, macOS, or WSL
./scripts/install-dependencies.sh --dry-run
./scripts/install-dependencies.sh

# Native Windows (Winget preferred; Chocolatey fallback)
.\scripts\install-dependencies.ps1 -DryRun
.\scripts\install-dependencies.ps1

It installs and validates:

• Git 2.19+
• a C compiler and make
• Go, required to build nvim-spotify
• Node.js and npm
• tree-sitter, required by current nvim-treesitter
• spotify-tui, which provides the spt executable
• a Nerd Font configured in the terminal
• recommended CLI tools: ripgrep, fd, fzf, and lazygit

Direct downloads are pinned and SHA-256 verified. OS toolchains use the detected package manager. Existing newer tools are retained; user-local tools shadow stale system copies without removing them. See bootstrap installer for supported platforms, non-interactive/check modes, paths, and ownership.

Example base packages:

# Ubuntu/Debian — package names can differ by release
sudo apt install build-essential curl fd-find fzf git golang-go nodejs npm ripgrep

# Arch Linux
sudo pacman -S base-devel curl fd fzf git go nodejs npm ripgrep

npm install --global tree-sitter-cli

Use the official Neovim release archive when a distribution package is older than 0.12.4.

Required Spotify setup

Spotify is part of the supported configuration, not an optional integration.

1. Install spotify-tui so spt is on PATH.
2. Complete spt's Spotify application and authentication setup.
3. Ensure go and make are available before :Lazy sync; lazy.nvim builds the NvimSpotify helper with make.
4. Run :checkhealth nvim_config and resolve every Spotify error.

The Neovim plugin does not consume SPOTIFY_CLIENT_ID or SPOTIFY_CLIENT_SECRET. Authentication belongs to spt; never commit Spotify credentials to this repository.

Interactive bootstrap installation opens the Spotify dashboard and launches the spt wizard. You still create/authorize the Spotify application because the installer cannot own your credentials. Unattended installation prints the manual next command.

Available commands:

• :Spotify — search Spotify
• :SpotifyDevices — select a playback device

The statusline displays Listening to: artist - title while playback information is available.

Install

Back up any existing configuration and state:

mv ~/.config/nvim ~/.config/nvim.bak
mv ~/.local/share/nvim ~/.local/share/nvim.bak
mv ~/.local/state/nvim ~/.local/state/nvim.bak
mv ~/.cache/nvim ~/.cache/nvim.bak

Clone this repository:

git clone https://github.com/hugo2006alm/nvim.git ~/.config/nvim
nvim

On first launch, lazy.nvim bootstraps itself and installs the configured plugin graph. Then run:

:Lazy sync
:checkhealth
:checkhealth nvim-treesitter
:checkhealth nvim_config

Authenticate GitHub Copilot with :Copilot auth when prompted.

User experience

Appearance

• Cyberdream colorscheme
• transparent background
• italic comments
• hidden fill characters
• borderless Telescope, fzf-lua, and Snacks pickers
• terminal colors supplied by Cyberdream
• custom global lualine with mode, branch, diagnostics, file details, buffers, tabs, Noice mode, updates, Copilot, Spotify, diff, progress, location, and clock

Custom keymap

Mode	Mapping	Action
Normal	<leader>tt	Toggle Cyberdream light/default mode

LazyVim owns its standard keymaps. They follow the current LazyVim release rather than preserving obsolete defaults.

Enabled LazyVim extras

• AI: Copilot and CopilotChat
• completion: LuaSnip
• debugging: core DAP support
• editor: Telescope
• formatting: Prettier
• languages: C/C++, Docker, Git, Java, JSON, Markdown, PHP, Prisma, Python, SQL, Tailwind CSS, and TypeScript
• UI: mini.animate

Additional custom plugins provide Cyberdream, Spotify, suda, and the custom lualine.

Repository layout

.
├── init.lua                    # Neovim entry point
├── lazyvim.json                # LazyVim extras and schema version
├── lazy-lock.json              # generated reviewed plugin snapshot
├── lua/
│   ├── config/                 # LazyVim bootstrap, keymaps, options, autocmds
│   ├── core/                   # shared local utilities
│   ├── nvim_config/            # health checks and Spotify requirement probes
│   └── plugins/                # custom plugin specifications
├── scripts/                    # cross-platform dependency bootstrap
├── tests/                      # headless regression checks
└── docs/                       # architecture, maintenance, ADRs, agent rules

See architecture for load order and ownership boundaries. See maintenance before updating dependencies.

Update

:Lazy update

Then review lazy-lock.json, restart Neovim, and run:

:checkhealth
:checkhealth nvim-treesitter
:checkhealth nvim_config

Never hand-edit plugin commits in lazy-lock.json; regenerate the snapshot through lazy.nvim. Major LazyVim migrations can update inherited UI and default mappings, but repository-defined controls must remain covered by tests.

Troubleshooting

• Startup after an update: run :Lazy, inspect failed tasks, then :Lazy sync.
• Treesitter failures: confirm tree-sitter --version, run :TSUpdate, then :checkhealth nvim-treesitter.
• Spotify failures: confirm spt, go, and make are on PATH; run :Lazy build nvim-spotify and :checkhealth nvim_config.
• Missing external tools: run the platform installer in check mode; see bootstrap installer.
• Copilot failures: run :Copilot status and repeat :Copilot auth if needed.
• Suspect snapshot regression: inspect git diff lazy-lock.json; restore the last known-good snapshot with normal Git history.

License

Apache License 2.0