Claude Code Neovim 插件

Claude Code AI 助手与 Neovim 之间的无缝集成

功能 • 要求 • 安装 • 配置 • 使用 • 贡献 • 讨论

此插件完全由 Claude Code 在 Neovim 终端中构建而成，随后又在自身内部使用 Claude Code 完成所有操作！

功能

• 🚀 通过单键即可在终端窗口中切换 Claude Code
• 🧠 支持命令行参数，如 --continue 和自定义变体
• 🔄 自动检测并重新加载由 Claude Code 修改的文件
• ⚡ 文件外部更改时实时更新缓冲区
• 📱 可自定义窗口位置和大小（包括浮动窗口）
• 🤖 与 which-key 集成（如果可用）
• 📂 自动将 git 项目根目录作为工作目录（若可用）
• 🧩 模块化且易于维护的代码结构
• 📋 使用 LuaCATS 进行类型注解，以获得更好的 IDE 支持
• ✅ 配置验证以防止错误
• 🧪 测试框架确保可靠性（44 项全面测试）

要求

• Neovim 0.7.0 或更高版本
• 已安装并可在 PATH 中访问的 Claude Code CLI 工具
• plenary.nvim（用于 git 操作的依赖项）

有关版本历史和更新，请参阅 CHANGELOG.md。

安装

使用 lazy.nvim

return {
  "greggh/claude-code.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim", -- 用于 git 操作的必需品
  },
  config = function()
    require("claude-code").setup()
  end
}

使用 packer.nvim

use {
  'greggh/claude-code.nvim',
  requires = {
    'nvim-lua/plenary.nvim', -- 用于 git 操作的必需品
  },
  config = function()
    require('claude-code').setup()
  end
}

使用 vim-plug

Plug 'nvim-lua/plenary.nvim'
Plug 'greggh/claude-code.nvim'
" 安装完成后，在 init.vim 中添加以下内容：
" lua require('claude-code').setup()

配置

可通过向 setup 函数传递表来配置插件。以下是默认配置：

require("claude-code").setup({
  -- 终端窗口设置
  window = {
    split_ratio = 0.3,      -- 终端窗口占屏幕的比例（水平分割为高度，垂直分割为宽度）
    position = "botright",  -- 窗口位置："botright"、"topleft"、"vertical"、"float" 等
    enter_insert = true,    -- 打开 Claude Code 时是否进入插入模式
    hide_numbers = true,    -- 隐藏终端窗口中的行号
    hide_signcolumn = true, -- 隐藏终端窗口中的符号列
    
    -- 浮动窗口配置（仅当 position = "float" 时适用）
    float = {
      width = "80%",        -- 宽度：列数或百分比字符串
      height = "80%",       -- 高度：行数或百分比字符串
      row = "center",       -- 行位置：数字、"center" 或百分比字符串
      col = "center",       -- 列位置：数字、"center" 或百分比字符串
      relative = "editor",  -- 相对于："editor" 或 "cursor"
      border = "rounded",   -- 边框样式："none"、"single"、"double"、"rounded"、"solid"、"shadow"
    },
  },
  -- 文件刷新设置
  refresh = {
    enable = true,           -- 启用文件更改检测
    updatetime = 100,        -- Claude Code 活动时的 updatetime（毫秒）
    timer_interval = 1000,   -- 检查文件更改的频率（毫秒）
    show_notifications = true, -- 文件重新加载时显示通知
  },
  -- Git 项目设置
  git = {
    use_git_root = true,     -- 打开 Claude Code 时将 CWD 设置为 git 根目录（若位于 git 项目中）
  },
  -- Shell 特定设置
  shell = {
    separator = '&&',        -- Shell 命令中使用的命令分隔符
    pushd_cmd = 'pushd',     -- 将目录压入堆栈的命令（例如，bash/zsh 的 'pushd'，nushell 的 'enter'）
    popd_cmd = 'popd',       -- 将目录从堆栈中弹出的命令（例如，bash/zsh 的 'popd'，nushell 的 'exit'）
  },
  -- 命令设置
  command = "claude",        -- 用于启动 Claude Code 的命令
  -- 命令变体
  command_variants = {
    -- 对话管理
    continue = "--continue", -- 恢复最近的对话
    resume = "--resume",     -- 显示交互式对话选择器

    -- 输出选项
    verbose = "--verbose",   -- 启用详细日志记录，提供逐轮完整输出
  },
  -- 键位映射
  keymaps = {
    toggle = {
      normal = "<C-,>",       -- 普通模式下切换 Claude Code 的键位，设为 false 可禁用
      terminal = "<C-,>",     -- 终端模式下切换 Claude Code 的键位，设为 false 可禁用
      variants = {
        continue = "<leader>cC", -- 普通模式下带有 continue 标志的 Claude Code 键位
        verbose = "<leader>cV",  -- 普通模式下带有 verbose 标志的 Claude Code 键位
      },
    },
    window_navigation = true, -- 启用窗口导航键位（<C-h/j/k/l>）
    scrolling = true,         -- 启用滚动键位（<C-f/b>）以实现页面上下滚动
  }
})

使用

快速入门

" 在你的 Vim/Neovim 命令或初始化文件中：
:ClaudeCode

-- 或者从 Lua 中调用：
vim.cmd[[ClaudeCode]]

-- 或者将其映射到一个键上：
vim.keymap.set('n', '<leader>cc', '<cmd>ClaudeCode<CR>', { desc = '切换 Claude Code' })

命令

基本命令：

• :ClaudeCode - 切换 Claude Code 终端窗口

会话管理命令：

• :ClaudeCodeContinue - 恢复最近的会话
• :ClaudeCodeResume - 显示交互式会话选择器

输出选项命令：

• :ClaudeCodeVerbose - 启用详细日志记录，显示每一步的完整输出

注意：命令会根据你配置中的 command_variants 自动生成功能。

键位映射

默认键位映射：

• <leader>ac - 切换 Claude Code 终端窗口（普通模式）
• <C-,> - 切换 Claude Code 终端窗口（普通模式和终端模式）

变体模式映射（如果已配置）：

• <leader>cC - 使用 --continue 标志切换 Claude Code
• <leader>cV - 使用 --verbose 标志切换 Claude Code

此外，在 Claude Code 终端中：

• <C-h> - 移动到左侧窗口
• <C-j> - 移动到下方窗口
• <C-k> - 移动到上方窗口
• <C-l> - 移动到右侧窗口
• <C-f> - 向下滚动一页
• <C-b> - 向上滚动一页

注意：使用 <C-f> 或 <C-b> 滚动后，需要按 i 键重新进入插入模式，才能继续向 Claude Code 输入内容。

当 Claude Code 修改了 Neovim 中打开的文件时，这些文件会自动重新加载。

浮动窗口示例

要在浮动窗口中使用 Claude Code：

require("claude-code").setup({
  window = {
    position = "float",
    float = {
      width = "90%",      -- 占据编辑器宽度的90%
      height = "90%",     -- 占据编辑器高度的90%
      row = "center",     -- 垂直居中
      col = "center",     -- 水平居中
      relative = "editor",
      border = "double",  -- 使用双线边框样式
    },
  },
})

工作原理

该插件：

1. 创建一个运行 Claude Code CLI 的终端缓冲区
2. 设置自动命令以检测磁盘上的文件变化
3. 当文件被 Claude Code 修改时自动重新加载
4. 提供方便的键位映射和命令来切换终端
5. 自动检测 Git 仓库，并将工作目录设置为 Git 根目录

贡献

欢迎贡献！请查看我们的 贡献指南，了解如何开始。

许可证

MIT 许可证 - 更多信息请参阅 LICENSE。

开发

有关如何设置开发环境、安装所有必要工具以及理解项目结构的完整指南，请参阅 DEVELOPMENT.md。

开发环境设置

该项目提供了全面的开发环境设置：

• DEVELOPMENT.md 中包含适用于所有平台的完整安装说明
• 用于代码质量的预提交钩子
• 包含 44 个全面测试的测试框架
• 静态分析和格式化工具
• 每周更新 Claude CLI 和相关依赖的工作流程

# 运行测试
make test

# 检查代码质量
make lint

# 设置预提交钩子
scripts/setup-hooks.sh

# 格式化代码
make format

社区

• GitHub Discussions - 获取帮助、分享想法并与社区其他用户交流
• GitHub Issues - 报告问题或提出功能建议
• GitHub Pull Requests - 参与项目贡献

致谢

• Anthropic 的 Claude Code - 本插件完全基于 Claude Code 构建。开发成本为 $5.42，使用了 17 分 12.9 秒的 API 时间
• Plenary.nvim - 测试框架和 Git 操作的核心依赖
• 语义化版本控制 - 本项目使用的版本号标准
• 贡献者公约 - 行为准则标准
• Keep a Changelog - 更改日志格式
• LuaCATS - 用于提升 IDE 支持的类型注解
• StyLua - Lua 代码格式化工具
• Luacheck - Lua 静态分析和 linter 工具

---

由 Gregg Housh 用心打造

claude-code.nvim 快速上手指南

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• Neovim: 版本需为 0.7.0 或更高。
• Claude Code CLI: 必须安装 Claude Code 命令行工具，并确保其已添加到系统的 PATH 环境变量中。
• 依赖插件: 需要安装 plenary.nvim，该插件用于处理 Git 操作和文件刷新功能。

提示：如果你尚未安装 Claude Code CLI，请参考官方仓库的安装说明。国内用户若遇到网络问题，可尝试配置代理或使用镜像源下载。

安装步骤

推荐使用流行的插件管理器进行安装。以下是针对主流管理器的配置示例：

方案一：使用 lazy.nvim (推荐)

在你的 lazy 配置文件中添加以下内容：

return {
  "greggh/claude-code.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim", -- Git 操作必需依赖
  },
  config = function()
    require("claude-code").setup()
  end
}

方案二：使用 packer.nvim

use {
  'greggh/claude-code.nvim',
  requires = {
    'nvim-lua/plenary.nvim', -- Git 操作必需依赖
  },
  config = function()
    require('claude-code').setup()
  end
}

方案三：使用 vim-plug

在 init.vim 中添加：

Plug 'nvim-lua/plenary.nvim'
Plug 'greggh/claude-code.nvim'

安装完成后，需在配置文件中运行初始化代码（Lua）：

require('claude-code').setup()

基本使用

安装并配置完成后，你可以通过以下方式快速启动 Claude Code：

1. 使用命令启动

在 Neovim 的命令模式下输入：

:ClaudeCode

这将直接在终端窗口中切换（打开/关闭）Claude Code 界面。

2. 配置快捷键 (可选)

为了方便操作，建议在 init.lua 中绑定快捷键。默认推荐使用 <leader>cc 或 <C-,>：

-- 绑定到 <leader>cc
vim.keymap.set('n', '<leader>cc', '<cmd>ClaudeCode<CR>', { desc = 'Toggle Claude Code' })

3. 核心功能体验

• 自动上下文：插件会自动检测当前项目是否为 Git 仓库，并将工作目录设置为 Git 根目录。
• 文件同步：当 Claude Code 修改了磁盘上的文件时，插件会自动检测并在 Neovim 中重新加载这些缓冲区，无需手动操作。
• 窗口导航：在 Claude Code 终端窗口中，你可以使用 <C-h/j/k/l> 在不同窗口间切换，使用 <C-f/b> 进行翻页。

进阶：浮窗模式

如果你更喜欢悬浮窗口而非分割屏，可以在 setup 配置中调整 window.position 为 "float"：

require("claude-code").setup({
  window = {
    position = "float",
    float = {
      width = "90%",
      height = "90%",
      row = "center",
      col = "center",
      border = "rounded",
    },
  },
})