# 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