156 lines
5.3 KiB
Markdown
156 lines
5.3 KiB
Markdown
# 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](https://github.com/folke/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**
|
|
```lua
|
|
-- 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](https://lazyvim.github.io/)
|
|
- [lazy.nvim Documentation](https://github.com/folke/lazy.nvim)
|
|
- [Neovim Lua Guide](https://neovim.io/doc/user/lua-guide.html)
|
|
|
|
## 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 |