Neovim config

My "personal" Neovim configuration. Always a work in progress.

Requirements

Neovim 0.12+ is required (the config uses the treesitter main-branch rewrite).

The following tools must be available on your PATH:

Dependency	Purpose
git	Plugin installation via lazy.nvim
fzf	Fuzzy finder backend for fzf-lua
ripgrep (rg)	Live grep inside fzf-lua
fd	File finding inside fzf-lua
A Nerd Font	Icons and UI symbols throughout

Optional — only needed for specific language support. Mason handles LSP server installation automatically.

Dependency	Used for
Node.js	JS/TS/JSON/CSS/HTML LSP servers
Python	pyright, ruff
PHP tools	intelephense, phpcs, etc.

Installation

1. Clone this repo:

   git clone https://github.com/<your-username>/nvim ~/.config/nvim

2. Launch Neovim. lazy.nvim will bootstrap itself and install all plugins automatically.
3. Restart Neovim. mason.nvim will install LSP servers and tools automatically.
4. Install a Nerd Font and configure your terminal to use it (required for icons to render correctly).

Working on this config

This repo carries machine-readable guidance so AI agents (and humans) can find their way around quickly.

Documentation map

AGENTS.md is the canonical architecture map: startup/load order, the global USER table, conventions, task recipes, and the commit + lazy-lock.json policy. Subdirectories carry their own AGENTS.md with local detail — lua/plugins/, lua/plugins/lsp/, lua/themes/, and plugin/. Each of those sits next to a tiny CLAUDE.md that imports it (@AGENTS.md), and the root CLAUDE.md does the same, so Claude Code loads the nearest guidance on demand while AGENTS.md stays the single source of truth.

Claude Code skills

On-demand workflows live in .claude/skills/. The recipe skills auto-activate when you edit files in their area; all can be invoked manually with /<name>.

Skill	What it does
/nvim-add-plugin <author/repo>	Add (or replace/remove) a plugin — fetches the GitHub "About" tagline and docs, generates the spec, handles the lockfile and scattered touchpoints
/nvim-lsp	Add or configure an LSP server / conform formatter / nvim-lint linter (auto-applies under lua/plugins/lsp/)
/nvim-theme	Add or edit a colorscheme / palette (auto-applies under lua/themes/, colors/)
/nvim-keymaps	Add or edit keybindings in USER.mappings (auto-applies on plugin/mappings.lua)
/nvim-verify	Format-check (stylua), lint (selene), and a headless smoke-load

Verifying changes

There is no test suite. Run /nvim-verify, or do it by hand: stylua --check and selene on the files you changed, plus a headless load (nvim --headless "+qa!") to confirm nothing errors on startup. stylua and selene are installed via Mason (~/.local/share/nvim/mason/bin).

To-do

• Audit and rework key mappings to better align with Vim's mapping philosophy
• Add code-preview.nvim to preview AI coding agent edits as a native diff before they're applied
• Migrate to nvim-ufo for folds using LSP
  • Use LSP as the primary fold provider with treesitter as a fallback
  • Recover the previous ufo implementation from git history (predates the satellite.nvim switch) and reuse its styling
• Break LSP server configs into separate files (on_attach ref — GitHub, on_attach ref — Reddit)
• Migrate to fzf-lua as a telescope replacement
  • Audit plugins that delegate to Telescope as a picker and wire up fzf-lua equivalents
  • Match existing Telescope functionality where possible; skip if the fzf-lua equivalent requires excessive boilerplate
  • Add a previewer to the fzf-lua snippet picker
• Fix LaunchURL to work with the default system browser while being system agnostic
• Create a skill that reads plugin documentation and add instructions to invoke it before any installation or config modification. Sources to cover:
  • Context7
  • Online on the git repo
  • Local in the codebase in .local/share/nvim/lazy
• Fix the send to quickfix actions in fzf-lua like file_tabedit and file_edit_or_qf to forward the files to trouble.nvim instead of the quickfix list. Consult the following plugins' documentation:
  • fzf-lua
  • snacks.nvim
  • trouble.nvim
• Migrate to conform.nvim / nvim-lint from none-ls
  • Surface active formatters/linters in the heirline statusline if feasible
• Add debugger: nvim-dap, nvim-dap-ui, nvim-dap-virtual-text
• Revisit migration to vim.pack for plugin management (investigated 2026-06; defer until dependencies land)
  • Staying on lazy.nvim: this config relies on dependencies, declarative lazy-load triggers, and lazy-specific integrations vim.pack doesn't yet support
  • Revisit when vim.pack adds lockfile-based dependency resolution and graduates from experimental

Plugins watch list

• persistence.nvim — Simple session management
• obsidian.nvim — ✨ AI Coding, Vim Style
• agentic.nvim — Agentic Chat Interface directly in Neovim with ACP providers from Claude-Code, Gemini, Codex, OpenCode, and Cursor-agent
• codecompanion.nvim — AI-powered coding
• avante.nvim — Use your Neovim like using Cursor AI IDE!
• mcphub.nvim — An MCP client for Neovim that seamlessly integrates MCP servers into your editing workflow with an intuitive interface for managing, testing, and using MCP servers with your favorite chat plugins.
• overseer.nvim — Task runner and job management

Plugins collections

• awesome-neovim
• neovimcraft.com

Sources

• Heavily inspired by Neelfrost — often mercilessly copy-pasting, especially at the beginning.
• Neil Sabde and his Neovim Lua From Scratch series were invaluable when I first dove into Vim/Neovim customization.
• Getting started using Lua in Neovim
• tjdevries, NvChad, williamboman, folke, LunarVim, doom-nvim