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
  • 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
• Comprehensive key bindings: Leader-based, Meta-X (Emacs-style), Ctrl-X, and function keys
• Claude Code integration: Built-in support with dedicated keymaps under <leader>a
• Note-taking workflow: Custom functions for capturing notes and snippets

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
• 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.