nvim-config/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 Neovim configuration written in Lua using Neovim's native package manager (vim.pack.add). The configuration is modular, with each feature organized into separate Lua files.

Core Structure

• init.lua - Main entry point, loads all modules and handles host-specific theming
• lua/ - All Lua modules
  • options.lua - Vim options, settings, and autocommands
  • plugins.lua - Plugin definitions and basic setup using vim.pack.add()
  • keymaps.lua - All key mappings including leader, Meta-X, Ctrl-X, and function key bindings
  • lsp.lua - LSP configuration (lua_ls, gopls) with lsp_signature
  • completion.lua - nvim-cmp completion setup
  • treesitter.lua - Treesitter configuration
  • autocmds.lua - Auto commands and event handling
  • diagnostics.lua - LSP diagnostics configuration
  • telescope_configuration.lua - Telescope picker configuration
  • terminal.lua - Terminal and toggleterm setup
  • vimwiki.lua - Vimwiki configuration
  • functions.lua - Custom utility functions
  • utils/ - Utility functions and overrides
    • t3_functions.lua - Custom functions for file finding, note capture, and navigation
    • t3_overrides.lua - Custom overrides
    • reload.lua - Configuration reloading utilities

Key Features

• Multi-host theming: Different TokyoNight themes based on hostname (xps13 uses "moon", Titan uses "storm")
• TTY compatibility: Automatic fallback to console-friendly themes and no icons when running in Linux console
• Dual picker system: Uses both FzfLua and Mini.pick for different workflows
• Triple picker integration: FzfLua, Mini.pick, and Telescope for comprehensive file/buffer navigation
• Comprehensive key bindings: Leader-based, Meta-X (Emacs-style), Ctrl-X, and function keys
• AI integration: Both Claude Code and Avante plugins for AI-assisted development
• Task management: TaskWarrior integration with dedicated keymaps
• Terminal integration: ToggleTerm and tmux navigation support
• Note-taking workflow: Custom functions for capturing notes and snippets
• Advanced buffer management: Barbar for visual buffer tabs with Alt+number navigation

Plugin Management

Uses Neovim's native package manager (vim.pack.add). No external package manager like lazy.nvim or packer.nvim is used.

Key Bindings Architecture

• Leader key: Space (<leader> = " ")
• Leader mappings: Organized by category (files, buffers, grep, git, tabs, AI)
• Meta-X mappings: Emacs-style command palette using Telescope
• Ctrl-X mappings: Additional workflows using Mini.pick
• Function keys: Quick access to common operations

LSP Configuration

• Enabled for Lua (lua_ls) and Go (gopls) with comprehensive settings
• Uses lsp_signature for parameter hints
• Glance plugin for references/definitions with custom keymaps (gR, gD, gY, gM)

Development Commands

This configuration doesn't have traditional build/test commands as it's a Neovim config. Key operations:

Configuration Management

• Reload config: Use the reload utilities in lua/utils/reload.lua
• Test changes: Restart Neovim or use :luafile % for individual files

Plugin Management

• Add plugins: Edit lua/plugins.lua and add to the vim.pack.add() table
• Plugin updates: Restart Neovim (native package manager handles updates)

Custom Functions

• :NeorgCapture - Capture notes using the custom note-taking workflow
• :CaptureSnip - Capture code snippets for LuaSnip
• :TWEditTask, :TWView, :TWUpdateCurrent, :TWSyncTasks, :TWToggle - TaskWarrior task management
• :UndotreeToggle - Visual undo tree navigation
• :Ranger, :RangerNewTab - File manager integration
• Various t3_* functions for file navigation and workflows

Important Conventions

File Organization

• All Lua code goes in lua/ directory
• Utilities and custom functions in lua/utils/
• Each major feature gets its own file (lsp.lua, completion.lua, etc.)

Keymaps

• Use descriptive desc fields for all keymaps (for which-key integration)
• Organize leader keymaps by category with sub-prefixes
• Function keys for frequently used operations

Host-Specific Behavior

The config detects hostname and adjusts theming accordingly. When adding host-specific features, follow the pattern in init.lua lines 17-45.

TTY Compatibility

The configuration automatically detects TTY environments and disables icons/complex UI elements. When adding new UI features, consider TTY fallbacks.

Key Binding Categories

• Leader mappings (<leader>): Organized with clear prefixes (<leader>f for files, <leader>g for grep, <leader>G for git, <leader>a for AI)
• Alt mappings: Buffer/tab navigation (Alt+1-9 for buffer jumping, Alt+Left/Right for buffer cycling)
• Meta-X mappings (<M-x>): Emacs-style command palette using Telescope
• Ctrl-X mappings (<C-x>): Alternative workflows using Mini.pick and TaskWarrior
• Function keys: Direct access to tools (F2 for UndoTree, F3 for Ranger, F9 for grep, F11/F12 for spell/wrap toggle)

AI Integration

• Claude Code: Primary AI assistant with keymaps under <leader>a for chat, diff management, and file operations
• Avante: Secondary AI integration (currently configured for Copilot provider)
• GitHub Copilot: Code completion integration via copilot.vim
• Were no longer using nvim_cmp having switched to coc