Skip to content

AGENTS.md

Latest commit

 

History

History
124 lines (96 loc) · 6.53 KB

AGENTS.md

File metadata and controls

124 lines (96 loc) · 6.53 KB
Raw

Neovim Configuration — Agent Guidelines

This is a personal Neovim configuration (~/.config/nvim/) using lazy.nvim as plugin manager, catppuccin as colorscheme, and Neovim's experimental built-in UI (vim._core.ui2) for cmdline/messages/popupmenu.

Architecture

init.lua                        → vim.loader, vim._core.ui2, ColorScheme autocmd, vim.cmd.colorscheme
├── lsp/                        → built-in vim.lsp.Config files (filename = server name)
└── lua/init.lua                → loads config/{key,options,autocmd,lazy,lsp}
    ├── config/key.lua          → basic keymaps (leader = Space)
    ├── config/options.lua      → editor options (default indent=4 spaces, winborder=rounded)
    ├── config/autocmd.lua      → global autocmds (winfixbuf, yank highlight, treesitter auto-enable/install)
    ├── config/lazy.lua         → lazy.nvim bootstrap, `spec = 'plugins'`
    ├── config/lsp.lua          → global LSP enable list + diagnostic config
    └── plugins/init.lua        → imports plugins.core + plugins.lang only

Plugin Organization: Base + Language Incremental

Plugins are split into two categories under lua/plugins/:

  • plugins/core/ — Infrastructure plugins used across all languages (LSP base, completion, formatter, treesitter, UI, git, navigation, etc.). Each file = one plugin concern.
  • plugins/lang/ — Language-specific plugin and formatter extensions. These files should only extend lazy specs or add language plugins; they are not where LSP server configs live anymore.

This pattern means:

  • LSP config belongs in lsp/<server>.lua and should return a vim.lsp.Config table: 
    -- lsp/foo_ls.lua
---@type vim.lsp.Config
return {
  settings = {
    foo = {
      enable = true,
    },
  },
}
  • LSP enablement is centralized in lua/config/lsp.lua via vim.g.lsp + vim.lsp.enable(vim.g.lsp).
  • Never duplicate core plugin specs in lang files. Use lang files to merge into existing specs like conform.nvim, or to add language-specific plugins such as flutter-tools.nvim.

LSP Configuration Pattern

LSP uses Neovim's built-in vim.lsp.config() + vim.lsp.enable() API (no custom wrapper types):

  • All server config tables live under lsp/*.lua, both generic and language-specific.
  • All enabled servers are listed in lua/config/lsp.lua.
  • Mason: plugins/core/lspconfig.lua maintains a flat mason_ensure list of mason-managed packages (servers + formatters/linters). Servers not managed by mason, such as fish_lsp, clangd, and ruff, are omitted from this list.
  • LSP keymaps and defaults live in plugins/core/lspconfig.lua inside the LspAttach autocmd, not in language files.

Treesitter Pattern

Treesitter is split across two places:

  • plugins/core/treesitter.lua configures textobjects and context plugins.
  • config/autocmd.lua owns vim.g.ts_langs and a FileType autocmd that lazily installs parsers and enables treesitter features on demand.

Do not add ensure_installed lists in language files unless the architecture changes again. If a new filetype should participate in the current auto-install flow, update vim.g.ts_langs.

Catppuccin Integration Pattern

Catppuccin integrations are enabled by returning a catppuccin spec alongside the plugin spec:

---@type LazyPluginSpec[]
return {
  { 'some/plugin.nvim', opts = { ... } },
  { 'catppuccin/nvim', opts = { integrations = { plugin_name = true } } },
}

This is used across plugins such as aerial, blink, dropbar, gitsigns, and snacks.

Code Style

  • Lua indent: 2 spaces (see .stylua.toml and .editorconfig)
  • StyLua is the formatter: column_width = 80, quote_style = AutoPreferSingle, call_parentheses = None, collapse_simple_statement = Always
  • Function calls without parens where idiomatic: require 'foo', vim.cmd.colorscheme 'catppuccin'
  • Plugin specs use ---@type LazyPluginSpec or ---@type LazyPluginSpec[] annotations
  • Each plugin file returns either a single spec (LazyPluginSpec) or a list (LazyPluginSpec[]), never a function
  • Keymaps inside plugin specs use the keys = { { lhs, rhs, desc = '...' } } lazy.nvim format
  • Use fzf-lua for fuzzy finding, search, and vim.ui.select
  • Use Snacks.toggle for toggle mappings
  • If filetype-specific buffer options are needed, prefer after/ftplugin/

Key Conventions

  • Leader: Space
  • Keymap groups (defined in which-key): <leader>c (Code), <leader>b (Buffer), <leader>f (Find Files), <leader>s (Search Grep), <leader>g (Git), <leader>n (Notification), <leader>t (Toggle)
  • LSP keymaps are set in lspconfig's LspAttach autocmd, not in individual lang files
  • Window navigation: <C-hjkl> in normal, <Tab> cycles windows
  • Visual line move: <C-jk> in visual mode
  • File explorer: \ (MiniFiles cwd), <leader>\ (MiniFiles current file)

Important Notes

  • Do NOT introduce noice.nvim — it was deliberately removed in favor of vim._core.ui2
  • Do NOT introduce telescope.nvim — fzf-lua is the fuzzy finder
  • Do NOT introduce neo-tree — mini.files is the file explorer
  • Avoid adding more folke ecosystem plugins unless clearly necessary; snacks.nvim is already used for a few focused utilities, but not as the general picker layer
  • Neovim version is bleeding-edge (uses vim._core.ui2, vim.lsp.config(), vim.lsp.enable())

Adding a New Language

  1. Create lua/plugins/lang/<language>.lua
  2. If the language needs LSP config, create lsp/<server>.lua returning a vim.lsp.Config table
  3. Add the server name to vim.g.lsp in lua/config/lsp.lua
  4. Add the server to mason_ensure in plugins/core/lspconfig.lua unless it is not mason-managed
  5. Return a LazyPluginSpec or LazyPluginSpec[] from the lang file that extends core specs:
    • Add formatter(s) to conform.nvim opts if needed
    • Add language-specific plugins as additional specs if needed
  6. If the language should use the current treesitter auto-install flow, add its filetype to vim.g.ts_langs in lua/config/autocmd.lua
  7. If the language needs custom buffer options, add after/ftplugin/<filetype>.lua
  8. No changes to plugins/init.lua are needed; lazy.nvim auto-imports from plugins/lang/

Adding a New Core Plugin

  1. Create lua/plugins/core/<plugin-name>.lua
  2. Return LazyPluginSpec (single) or LazyPluginSpec[] (if catppuccin integration needed)
  3. Use lazy-loading (event, ft, cmd, keys) wherever possible
  4. No changes to plugins/init.lua needed