LazyVim-based Neovim configuration with project-local startup, plugin state, and cache directories.
Current baseline:
- LazyVim with local overrides under
lua/. - Comma is the leader key.
- Snacks provides pickers, file explorer, terminal integration, and UI prompts.
- Mason is disabled; LSP and tool binaries come from
PATH. - Native
vim.lspconfig lives in this repo. - Linux x86_64 airgap builds support a GitHub release AppImage and a local extracted tarball.
Use the wrapper script so Neovim sees this repository as its config and stores
runtime state under .xdg/:
scripts/nvim.shTo use a specific Neovim binary:
NVIM_BIN=/path/to/nvim scripts/nvim.sh- Start Neovim once with
scripts/nvim.shso lazy.nvim can bootstrap plugins. - Run
make verifyto check startup, plugin smoke tests, and external tools. - Run
make check-external-toolsto see optional local binaries used by LSP, terminal, and AI integrations. - Run
make healthcheckwhen you want to refresh the captured health report.
The full plugin inventory lives in docs/plugins.md. This is the quick map for day-to-day use.
| Area | Plugins | Source | Main keys |
|---|---|---|---|
| Plugin/runtime foundation | lazy.nvim, LazyVim, lazydev.nvim, persistence.nvim, plenary.nvim |
LazyVim plus local bootstrap | :Lazy |
| Completion and snippets | blink.cmp, mini.snippets, friendly-snippets |
LazyVim | Completion appears in insert mode. |
| Files, buffers, search | snacks.nvim pickers/explorer, todo-comments.nvim, flash.nvim, trouble.nvim, grug-far.nvim |
LazyVim with local key overrides | ,f, ,F, ,s, ,S, ,b, ,d, mf, ,psr, ,pst, ,psT |
| UI and navigation | which-key.nvim, noice.nvim, nvim-treesitter-context, lualine.nvim, bufferline.nvim, mini.icons |
LazyVim with local overrides | ,tc, ,psn..., <Tab>, <S-Tab>, ,B... |
| Editing | mini.surround, mini.ai, mini.comment, mini.pairs, mini.align, mini.splitjoin, mini.trailspace, native nvim.undotree |
LazyVim plus local Mini/native setup | gc, gsa, gsd, gsr, ga, gA, gS, ,cw, ,u, ,q |
| Git and terminal | gitsigns.nvim, vim-fugitive, vim-dispatch, snacks.nvim terminal, nvim-unception |
LazyVim plus local additions | ,tg, ,te, ,tt, :Git, :Dispatch, :Make |
| AI terminal workflow | External crush CLI through snacks.nvim terminal |
Local helper, host-provided CLI | ,aa, ,aA, ,af, ,aF, visual ,as, visual ,aS |
| LSP, formatting, linting | Native vim.lsp, conform.nvim, nvim-lint |
Local native LSP plus LazyVim integrations | gd, gr, K, gK, ,ca, ,cr, ,cl |
| Treesitter | nvim-treesitter, nvim-treesitter-textobjects, nvim-ts-autotag, nvim-ts-context-commentstring, ts-comments.nvim |
LazyVim with local parser list | Syntax, textobjects, comments, and context header are automatic. |
| Themes | tokyonight.nvim, nord-vim, catppuccin, kanagawa.nvim |
LazyVim plus local theme profiles | ,tc |
Most important keys:
| Key | Action |
|---|---|
,f / ,s / ,b |
Find files, grep text, or pick buffers instantly. |
,F / ,S |
Limit file or grep search to a chosen directory. |
,d / mf |
Open the project tree or reveal the current file in it. |
<Tab> / <S-Tab> |
Move through buffers in the tabline. |
,q / ,B... |
Close the current buffer or use buffer-management actions. |
gd, gr, K, ,ca, ,cr |
LSP navigation, references, hover, code action, and rename. |
ga, gA, gS, gsa, gsd, gsr, gc |
Align, split/join, surround, and comment editing helpers. |
,te, ,tt, ,tg |
Open terminal and lazygit workflows. |
,aa, ,af, visual ,as |
Open Crush, ask about the current file, or ask about selected lines. |
,u, ,cw, ,tc |
Undo tree, trim trailing whitespace, and colorscheme picker. |
Run the headless startup test:
tests/run.shThe test fails on startup errors or warnings.
Run the broader migrated-plugin smoke checks:
make verify-pluginsRun all local baseline checks:
make verifyCheck external tools expected by optional integrations:
make check-external-toolsShow the current plugin migration queue:
make migration-statusCapture a healthcheck report:
make healthcheckBuild and verify a local Linux x86_64 airgap tarball:
make airgap-bundle
make verify-airgap-bundle TARBALL=dist/nvim-airgap-linux-x86_64-*.tar.gzBuild and verify a local Linux x86_64 release-style AppImage:
make airgap-appimage
make verify-airgap-appimage APPIMAGE=dist/nvim-airgap-linux-x86_64.AppImageThe GitHub Actions workflow builds the AppImage from Fedora userspace,
publishes a versioned release named airgap-YYYY.MM.DD-<short-sha>, and also
updates the moving latest release. Use the versioned release when you need a
stable artifact reference, and latest when you want the newest successful
build.
Run the release AppImage normally:
chmod +x nvim-airgap-linux-x86_64.AppImage
./nvim-airgap-linux-x86_64.AppImageRun it on systems without FUSE support:
chmod +x nvim-airgap-linux-x86_64.AppImage
./nvim-airgap-linux-x86_64.AppImage --appimage-extract
./squashfs-root/AppRunThe AppImage uses bundled config and plugin data, but writes state, cache,
runtime sockets, and temporary files to per-effective-user locations:
<effective-home>/.local/state/nvim-airgap,
<effective-home>/.cache/nvim-airgap, and
${TMPDIR:-/tmp}/nvim-airgap-<effective-uid>. The launcher resolves
<effective-home> from the effective UID instead of trusting inherited
$HOME, so sudo/root sessions use root's home and do not create root-owned
files in the invoking user's directories. Override these with
NVIM_AIRGAP_STATE_HOME, NVIM_AIRGAP_CACHE_HOME, or
NVIM_AIRGAP_RUNTIME_DIR when needed.
If an older AppImage already created root-owned files in your normal user's home, remove the cache/state once or change ownership before running as that user again.
Mason is disabled. Language servers, formatters, linters, debuggers, and AI CLI
tools should be installed outside this config and discovered on PATH.
See docs/external-tools.md for details.
Known accepted healthcheck warnings are tracked in docs/healthcheck-findings.md. Missing optional tools should be installed outside Neovim or left documented as accepted follow-up work.