Imported from jinzhongjia/neovim-config (AGENTS.md). Install upstream with npx skills add jinzhongjia/neovim-config. Copyright stays with the author.

AGENTS.md - Neovim Configuration

Commands

• Format: stylua lua/ (format Lua files)
• Validate: Open Neovim and run :checkhealth
• Plugins: :Lazy sync (install/update), :Lazy profile (performance)
• LSP: :Mason (manage LSP servers), :LspInfo (view attached LSP)

Code Style (enforced by .stylua.toml)

• Indent: 4 spaces, 120 char line width, Unix line endings
• Quotes: Double quotes preferred
• Naming: snake_case for functions/variables
• Comments: Use Chinese for inline comments when explaining complex logic

Project Structure

nvim-config/
├── init.lua                 # Entry point, loads core and plugins
├── lua/
│   ├── core/                # Core settings
│   │   ├── init.lua         # Loads all core modules
│   │   ├── basic.lua        # Basic vim options
│   │   └── util.lua         # Utility functions
│   ├── plugin.lua           # lazy.nvim bootstrap
│   └── plugins/             # Plugin configurations (one file per plugin/group)
├── after/
│   └── lsp/                 # Language-specific LSP configs (Neovim 0.11+)
└── plugin/                  # Auto-loaded Lua files for custom commands

Plugin Configuration Pattern

Basic Structure

All plugin configs in lua/plugins/ must follow this pattern:

return
--- @type LazySpec
{
    {
        "author/plugin-name",
        event = "VeryLazy",           -- or: ft, cmd, keys for lazy loading
        dependencies = { "dep/name" }, -- optional
        opts = {},                     -- plugin options (calls setup automatically)
    },
}

Loading Strategies

Configuration Approaches

1. Simple plugins: Use opts = {} (uses defaults)
2. Custom options: Use opts = { key = value }
3. Complex setup: Use config = function() ... end

Examples

Simple plugin (defaults):

{
    "folke/todo-comments.nvim",
    event = "VeryLazy",
    dependencies = { "nvim-lua/plenary.nvim" },
    opts = {},
}

Plugin with options:

{
    "stevearc/conform.nvim",
    event = "VeryLazy",
    opts = {},
    keys = {
        {
            "<leader>f",
            function()
                require("conform").format({ async = false, lsp_fallback = true })
            end,
            mode = { "n", "v" },
            desc = "Format file or range",
        },
    },
}

Plugin with config function:

{
    "kevinhwang91/nvim-hlslens",
    event = "VeryLazy",
    config = function()
        require("hlslens").setup()
        -- Custom keymaps here
        vim.keymap.set("n", "n", [[<Cmd>execute('normal! ' . v:count1 . 'n')<CR><Cmd>lua require('hlslens').start()<CR>]])
    end,
}

LSP Configuration (Neovim 0.11+)

Architecture

This config uses Neovim 0.11's native LSP API:

• mason.nvim: Manages LSP server binaries
• mason-lspconfig.nvim: Bridges Mason and LSP, auto-enables servers
• nvim-lspconfig: Provides default LSP configurations
• blink.cmp: Handles LSP capabilities automatically

Adding a New LSP Server

1. Add to ensure_installed in lua/plugins/lsp.lua:

ensure_installed = { "gopls", "basedpyright", "ts_ls", "lua_ls", "NEW_SERVER" },

2. Create language-specific config in after/lsp/<server_name>.lua:

-- after/lsp/NEW_SERVER.lua
return {
    settings = {
        -- Server-specific settings
    },
}

LSP Config File Structure

Files in after/lsp/ are automatically loaded by Neovim 0.11 and merged with defaults.

-- after/lsp/<server_name>.lua
return {
    settings = {
        server_name = {
            -- Enable features
            feature = true,
            -- Configure analyses
            analyses = {
                unusedparams = true,
            },
            -- Configure hints
            hints = {
                parameterNames = true,
            },
        },
    },
}

Current LSP Servers

Keybinding Guidelines

• Before adding keybindings: Search the codebase for existing uses to avoid conflicts
• Check for conflicts: Use grep to search lua/plugins/ for the key pattern
• All keybindings need descriptions: Use desc = "Description" for better discoverability
• Prefer <leader> prefix: Use <leader> for custom keybindings

Important Notes

• VimL plugins: Do NOT use opts = {} for VimL plugins (they don't have Lua setup())
• Lazy loading: Prefer lazy loading to improve startup time
• Dependencies: Declare dependencies explicitly in dependencies field
• Type annotations: Use --- @type LazySpec for better LSP support in plugin files

Claude Code 集成 (claudecode.nvim)

概述

claudecode.nvim 提供 Claude Code CLI 的原生 Neovim 集成，通过 WebSocket 协议实现与官方 VS Code 扩展相同的功能。

核心特性

• 实时上下文追踪: Claude 能看到你当前编辑的文件和选中的代码
• 原生 Diff 支持: 直接在 Neovim 中查看和应用 Claude 提议的修改
• Git 仓库感知: 自动识别项目根目录，提供完整项目上下文
• 文件树集成: 从 NvimTree 直接添加文件到 Claude 上下文

快捷键

典型工作流

1. 启动 Claude: 按 <leader>ac 打开浮动终端
2. 添加上下文:
   • 方式一: 选中代码按 <leader>as 发送选中内容
   • 方式二: 按 <leader>ab 添加当前文件
   • 方式三: 在 NvimTree 中按 <leader>as 添加文件
3. 与 Claude 对话: 在终端中描述你的需求
4. 查看修改: Claude 提议修改时自动打开 diff 窗口
5. 应用修改:
   • 按 <leader>aa 接受修改
   • 按 <leader>ad 拒绝修改
   • 或直接编辑 diff 再保存
6. 关闭窗口: 在终端模式按 <C-,> 隐藏

配置说明

配置文件: lua/plugins/claudecode.lua

关键配置项:

• terminal_cmd = nil: 使用系统 PATH 中的 claude 命令
• git_repo_cwd = true: 在 git 仓库根目录运行，提供完整项目视图
• focus_after_send = true: 发送代码后自动聚焦终端，方便继续对话
• keep_terminal_focus = true: 打开 diff 后保持焦点在终端

故障排查

• Claude 无法连接? 检查 :ClaudeCodeStatus 并验证 lock 文件存在于 ~/.claude/ide/
• 需要调试日志? 在 opts 中设置 log_level = "debug"
• 终端问题? snacks.nvim 已启用 terminal 支持，无需额外配置

与其他 AI 工具的关系

它们互补而不重叠，可以同时使用。

FFF 文件搜索集成 (fff.nvim)

快捷键

命令

保留的其他搜索工具

• grug-far.nvim: 搜索替换（fff 不支持替换），快捷键 <leader>gf*
• flash.nvim: 行内快速跳转
• hlslens.nvim: 搜索高亮增强
• snacks.nvim picker: Buffers、Recent、LSP 符号、诊断

For LLM

LLM can modify this file if necessary to keep it up to date with changes in the configuration structure or best practices.