Skip to content

CLAUDE.md

Latest commit

 

History

History
136 lines (106 loc) · 5.24 KB

CLAUDE.md

File metadata and controls

136 lines (106 loc) · 5.24 KB

CLAUDE.md

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

Overview

This is a personal Neovim configuration using lazy.nvim as the plugin manager. The config is organized under the phaezer namespace with a modular structure.

Architecture

Core Structure

  • init.lua: Entry point that loads core config and bootstraps lazy.nvim
  • lua/phaezer/config/: Core Neovim configurations loaded at startup
    • init.lua: Orchestrates loading of all config modules
    • opt.lua: Vim options
    • keymap.lua: Base keybindings
    • lsp.lua: LSP system configuration with custom toggle/diagnostic features
    • vars.lua: Global variables
    • user_commands.lua: Custom user commands
    • autocmd.lua: Autocommands
    • highlights.lua: Highlight groups
  • lua/phaezer/core/: Shared utilities used throughout the config
    • keys.lua: Keymap helper functions
    • icons.lua: Icon definitions
    • util.lua: General utilities
    • colors.lua: Color utilities
    • files.lua: File operations
    • modules.lua: Module loading helpers
  • lua/phaezer/plugins/: Plugin configurations organized by category
    • Each plugin file returns a lazy.nvim spec table
  • lsp/: Individual LSP server configurations
    • Each file exports a config table with name, cmd, filetypes, root_markers, settings
    • LSP files are auto-discovered and enabled via vim.lsp.enable() in config/lsp.lua

Plugin Organization

Plugins are categorized into subdirectories:

  • ai/: AI assistants (copilot, avante, opencode, sidekick)
  • completion/: Completion engines (blink.cmp, luasnip)
  • editing/: Text editing enhancements (surround, pairs, substitute, etc.)
  • vcs/: Git integrations (gitsigns, lazygit, neogit, fugitive, diffview)
  • lsp/: LSP related plugins (mason, conform, trouble, outline, etc.)
  • ui/: UI enhancements (lualine, neotree, snacks, whichkey, etc.)
  • navigation/: Navigation tools (flash, mini-ai, todo-comments)
  • highlights/: Syntax and visual highlighting (treesitter, rainbow-delimiters, etc.)
  • tools/: Utility plugins (toggleterm, floaterm, overseer, dadbod, etc.)
  • text/: Text/document specific (obsidian, markview, headlines, etc.)
  • themes/: Colorschemes
  • langs/: Language-specific plugins organized by language (ansible/, go/, rust/)
  • folding/: Code folding (ufo)
  • integrations/: External tool integrations (kitty, tmux)
  • debug/: Debug adapters (dap-python, dap-go)
  • experimental/: Experimental plugins (only loaded if NVIM_EXPERIMENTAL env var is set)

LSP System

The LSP configuration (lua/phaezer/config/lsp.lua) implements:

  1. Auto-discovery: Scans lsp/*.lua for server configs and auto-enables them
  2. Global capabilities: Configures folding support for all LSP servers
  3. Diagnostic modes: Custom diagnostic display modes (minimal, default, detailed, detailed_lines)
    • Toggle with :SetDiagnosticConfig <mode>
  4. LSP Toggle: Ability to enable/disable individual LSP servers without restarting Neovim
    • :ToggleLSP <name> or :ToggleLSPSelect for interactive selection
  5. Custom middleware: Intercepts buf_attach_client to track attached buffers and prevent reattachment when disabled

Keymap System

The custom keymap system (lua/phaezer/core/keys.lua) provides:

  • map() function that accepts table-based keybinding definitions
  • Support for common options like mode, prefix, desc, plugin
  • OS-specific and VS Code-specific keybinding filtering
  • Automatic plugin attribution in descriptions

Example usage:

map {
  mode = 'n',
  prefix = '<leader>w',
  { 's', '<CMD>split<CR>', desc = 'split' },
  { 'v', '<CMD>vsplit<CR>', desc = 'split |' },
}

Theme Selection

Default theme is tokyonight, but can be overridden with NVIM_THEME environment variable.

Key Bindings

  • Leader key: <Space>
  • Local leader: <Space>
  • Window management: <leader>w prefix
  • Buffer management: <leader>b prefix
  • Diagnostics/LSP: <leader>x prefix
  • Actions: <leader>k prefix
  • UI toggles: <leader>u prefix
  • File explorer: <leader>e or <leader>n prefix
  • Terminal: <C->(horizontal),t` prefix for others
  • Inspections: <leader>i prefix

Adding New Plugins

  1. Create a new file in the appropriate lua/phaezer/plugins/<category>/ directory
  2. Return a lazy.nvim spec table
  3. Add keybindings using the keys property or via lua/phaezer/config/keymap.lua

Adding New LSP Servers

  1. Create a new file lsp/<servername>.lua
  2. Export a table with: name, cmd, filetypes, root_markers, settings
  3. The LSP will be auto-discovered and enabled on next restart

Completion

Uses blink.cmp with multiple sources:

  • LSP (highest priority, score_offset=100)
  • Path, Buffer, Snippets, Ripgrep
  • Copilot integration
  • Dadbod for SQL files
  • LazyDev for Lua files
  • Dictionary for markdown/norg files

Completion can be toggled on/off with <leader>kc.

Custom User Commands

  • :SetDiagnosticConfig <mode>: Change diagnostic display mode
  • :ToggleLSP <name>: Toggle specific LSP on/off
  • :ToggleLSPSelect: Interactive LSP toggle menu

Development Plugins

Local development plugins are stored in ~/projects/nvim and pattern-matched with phaezer.