nvim1/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Architecture Overview

This is a modern Neovim configuration built around the lazy.nvim plugin manager. The configuration follows a modular structure:

• Entry point: init.lua loads core modules in sequence: options, mappings, lazy.nvim setup, and autocmds
• Plugin management: Uses lazy.nvim with plugins defined in lua/plugins/ directory
• LSP configuration: Centralized in lua/functions/lsp.lua with server-specific settings in lua/lsp/
• Shared utilities: Common constants and tools in lua/commons/init.lua
• Configuration modules: Core settings split into separate files in lua/configs/

Key Components

LSP Setup

• Supports both Neovim 0.11+ new LSP config API and legacy setup
• LSP servers are defined in commons.servers array
• Server-specific settings live in lua/lsp/{server}.lua files
• Uses blink.cmp for completion capabilities
• LSP servers supported: lua_ls, gopls, clangd, bashls, pyright, yamlls, ts_ls, rust_analyzer
• Mason.nvim auto-installs: stylua, lua-language-server, gopls, pyright

Plugin Architecture

• All plugins defined as lazy.nvim specs in lua/plugins/
• Custom lazy file event handling in utils/plugins.lua
• Key plugins: blink.cmp (completion), conform.nvim (formatting), fzf-lua (fuzzy finding), treesitter, lspconfig

Formatting

• Conform.nvim handles formatting with <leader>ff keybind
• Format-on-save enabled with 500ms timeout, format command uses 3000ms timeout
• Configured formatters: stylua (Lua), black (Python), rustfmt (Rust), prettier (JS), shfmt (shell)
• Stylua configured with --collapse-simple-statement Always

Common Development Tasks

Adding New LSP Server

1. Add server name to commons.servers array in lua/commons/init.lua
2. Create server config file at lua/lsp/{server}.lua with settings table
3. Ensure server is installed via Mason or system package manager

Adding New Plugin

1. Create plugin spec file in lua/plugins/{name}.lua
2. Return lazy.nvim spec table with plugin URL and configuration
3. Plugin will be auto-loaded by lazy.nvim

Key Mappings

• Leader key: <Space>
• Save: <leader>s
• Smart buffer delete: <leader>q (switches to next buffer, or opens explorer if last buffer)
• Quit: <leader>qq (force quit: <leader>qqq)
• Format code: <leader>ff
• Toggle comment: mm (normal/visual mode)
• Show diagnostics: <leader>d (uses Snacks picker)

File Structure Conventions

• Plugin configs: lua/plugins/{plugin-name}.lua
• LSP server configs: lua/lsp/{server-name}.lua
• Shared utilities: lua/commons/ and lua/utils/
• Core configuration: lua/configs/

Version Compatibility

• Uses commons.tools.is_version_gte_0_11() to detect Neovim 0.11+ for new LSP API
• Maintains backward compatibility with older Neovim versions
• Big file handling configured for files >50KB