# 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