nvim/AGENTS.md

AGENTS.md - LazyVim Configuration Guide

This document provides essential information for AI agents working with this LazyVim Neovim configuration.

Overview

This is a LazyVim-based Neovim configuration located at /Users/alice/.config/nvim. LazyVim is a Neovim distribution that provides a solid foundation for modern Neovim development with lazy loading and sensible defaults.

Project Structure

~/.config/nvim/
├── init.lua                 # Main entry point
├── lazy-lock.json          # Plugin version lock file
├── lazyvim.json            # LazyVim configuration
├── stylua.toml             # Lua code formatter config
├── lua/
│   ├── config/
│   │   ├── autocmds.lua    # Auto commands
│   │   ├── keymaps.lua     # Key mappings
│   │   ├── lazy.lua        # Lazy.nvim setup
│   │   └── options.lua     # Neovim options
│   └── plugins/
│       ├── example.lua     # Example plugin configuration
│       ├── general.lua     # General plugins (tmux-navigator)
│       ├── harpoon.lua     # Harpoon file navigation
│       └── ui.lua          # UI plugins (catppuccin theme)

Key Configuration Details

LazyVim Version

• Version: 8
• Install Version: 8
• Extras: JSON, Markdown, and Python language support

Plugin Management

• Uses lazy.nvim for plugin management
• Plugins are lazy-loaded by default for performance
• Auto-updates are enabled but notifications are disabled

Custom Plugins

1. Harpoon (lua/plugins/harpoon.lua)

• Purpose: Fast file navigation and project management
• Key Bindings:
  • <leader>H: Add current file to harpoon
  • <leader>h: Toggle harpoon quick menu
  • <leader>1-9: Jump to harpoon file 1-9
• Configuration: Auto-save on toggle, dynamic menu width

2. Tmux Navigator (lua/plugins/general.lua)

• Purpose: Seamless navigation between Neovim and tmux panes
• Commands: TmuxNavigateLeft/Down/Up/Right/Previous

3. Catppuccin Theme (lua/plugins/ui.lua)

• Purpose: Modern, beautiful color scheme
• Theme: catppuccin-frappe (default)
• Features: Extensive integration with LSP, treesitter, and other plugins

Important Files for Agents

Configuration Files

• init.lua: Entry point - just loads config.lazy
• lua/config/lazy.lua: Main lazy.nvim configuration
• lua/config/options.lua: Neovim options and settings
• lua/config/keymaps.lua: Key mappings and shortcuts
• lua/config/autocmds.lua: Auto commands and file type settings

Plugin Files

• Each file in lua/plugins/ represents a plugin or group of related plugins
• Plugin configurations return a table with plugin specifications
• Use lazy = true for lazy loading, lazy = false for immediate loading

Development Guidelines for Agents

1. Adding New Plugins

-- In lua/plugins/your-plugin.lua
return {
  {
    "author/plugin-name",
    version = "*", -- or specific version
    lazy = true,   -- or false for immediate loading
    opts = {
      -- plugin options
    },
    keys = {
      -- key mappings
    },
  },
}

2. Modifying Existing Plugins

• Edit the corresponding file in lua/plugins/
• Use opts table to override default options
• Use keys table to add custom key mappings

3. Key Mapping Conventions

• Leader key is typically <leader> (usually space)
• Use descriptive desc fields for all key mappings
• Group related mappings in the same plugin file

4. LazyVim Integration

• LazyVim provides many built-in plugins and configurations
• Use LazyVim/LazyVim import to access core functionality
• Override LazyVim defaults in your plugin files

Common Tasks for Agents

Adding Language Support

1. Check if LazyVim already provides the language support
2. If not, add language-specific plugins to lua/plugins/
3. Configure LSP, treesitter, and other language tools

Customizing UI

1. Modify lua/plugins/ui.lua for theme changes
2. Add statusline, bufferline, or other UI plugins
3. Configure colorscheme in the LazyVim options

Adding Key Mappings

1. Add global mappings to lua/config/keymaps.lua
2. Add plugin-specific mappings in the plugin file
3. Use vim.keymap.set() for modern key mapping

Performance Optimization

1. Ensure plugins are properly lazy-loaded
2. Use lazy = true for non-essential plugins
3. Configure cmd, event, or ft triggers for lazy loading

Troubleshooting

Plugin Issues

• Check lazy-lock.json for version conflicts
• Use :Lazy to manage plugins interactively
• Check :checkhealth for system issues

Configuration Issues

• Validate Lua syntax with :luafile %
• Check for circular dependencies in plugin imports
• Use :LazyVim profile for performance analysis

Resources

• LazyVim Documentation
• lazy.nvim Documentation
• Neovim Lua Guide

Notes for AI Agents

• This configuration is optimized for modern Neovim development
• Always test changes in a safe environment before applying
• Respect the existing code style and structure
• Use descriptive commit messages when making changes
• Consider performance implications of new plugins