CodeCompanion CLI 交互指南:在 Neovim 内驱动 Claude Code 与 Codex 等终端 Agent
CodeCompanion CLI 交互指南:在 Neovim 内驱动 Claude Code 与 Codex 等终端 Agent
导读
CodeCompanion 的 CLI 交互(Command-Line Interface interaction)让你无需离开 Neovim,即可与 Claude Code、Codex 这类拥有命令行界面的 AI Agent 直接对话:把当前缓冲区、可视选区、LSP 诊断、终端输出等编辑器上下文,以按键级的速度共享给 CLI Agent,并直接在 Neovim 终端中查看与操作 Agent 的回复。读完本文,你将掌握 :CodeCompanionCLI 命令与 require("codecompanion").cli() Lua API 的完整用法、Agent 与 Provider 的配置方式、上下文注入(#{...})语法,以及 hooks 集成、自动提交等进阶工作流,并理解其底层在 CLI 交互模块 中的真实实现。
一、为什么需要 CLI 交互
与纯 API 对话不同,Claude Code、Codex 这类 Agent 以交互式 CLI 进程的形式运行。以往要给它共享上下文,你不得不切到终端、按 @ 搜索文件或触发斜杠命令;要分享一段代码,还得手动复制粘贴。CodeCompanion 的 CLI 交互将这一切压缩为几次按键:
- 直接从 Neovim 缓冲区共享当前文件(
#{buffer})、全部打开文件(#{buffers})、LSP 诊断(#{diagnostics})或最近终端输出(#{terminal}); - 用可视选区或整行命令直接把代码与提示词一起送入 CLI Agent;
- 在 Neovim 内的终端窗口查看 Agent 输出,无需离开编辑器;
- 通过 hooks 让 CodeCompanion 的事件系统感知一轮对话的开始与结束(例如驱动代码评审等依赖“回合”边界的功能)。
其入口实现见 CodeCompanion.cli(),整体模块位于 interactions/cli。
二、发起一次 CLI 交互
2.1 基本命令
使用 :CodeCompanionCLI 即可启动一个新的 CLI 交互,CodeCompanion 会使用配置中 interactions.cli.agent 指定的默认 Agent。想要临时切换 Agent,可以在命令后追加 agent=<agent_name>:
:CodeCompanionCLI
:CodeCompanionCLI agent=codex
也可以像聊天缓冲区一样,用 require("codecompanion").toggle() 在“打开/隐藏”之间切换 CLI 窗口(内部实现为 CLI.toggle,若尚无实例则创建,否则在可见与隐藏间切换)。在 CLI 缓冲区中,{ 和 } 可以循环切换所有聊天与 CLI 交互(对应 keymaps 中的 next_chat / previous_chat,底层调用 registry.move)。
注意:若配置中没有任何 Agent,
:CodeCompanionCLI会失败并提示CLI agent 'xxx' not found in config——详见 CLI.create。使用 CLI 交互前必须先定义至少一个 Agent(见下文“配置 CLI Agent”)。
2.2 命令的解析规则
:CodeCompanionCLI 由 commands/init.lua 注册,解析规则如下:
- 形如
key=value的参数会被提取为选项(目前支持agent=),其余部分拼接为提示词; - 无提示词时:若处于可视模式(
'<,'>范围)则把选区作为上下文发送,否则新建一个 CLI 交互实例; - 命令带
!(bang)时自动提交提示词(等价于submit = true); - 输入
Ask打开提示词输入缓冲区;输入Install触发 hooks 安装(见下文“Hooks 集成”)。
三、配置 CLI Agent
CLI 交互要求你在 setup 配置 中定义 Agent,完整示例见 doc/configuration/cli.md:
require("codecompanion").setup({
interactions = {
cli = {
agent = "claude_code", -- 默认 Agent
agents = {
claude_code = {
cmd = "claude", -- 启动命令
args = {}, -- 传给命令的参数
description = "Claude Code CLI",
provider = "terminal", -- 默认即可
},
},
},
},
})
Agent 各字段说明:
| Option | Type | Description |
|---|---|---|
cmd |
string |
要运行的命令(如 "claude"、"codex") |
args |
table |
传给命令的附加参数 |
description |
string |
在 Action Palette 中显示的描述 |
provider |
string |
使用的 Provider,默认 "terminal" |
3.1 多 Agent 并存与切换
require("codecompanion").setup({
interactions = {
cli = {
agent = "claude_code",
agents = {
claude_code = { cmd = "claude", args = {}, description = "Claude Code CLI" },
codex = { cmd = "codex", args = {}, description = "OpenAI Codex CLI" },
},
},
},
})
然后通过 :CodeCompanionCLI agent=codex <prompt> 使用指定 Agent。Lua API 侧则在 opts 中传 agent:require("codecompanion").cli({ agent = "codex" })。
从源码看,CLI.create 会根据 args.agent or config.interactions.cli.agent 查找 Agent 配置;当传入提示词时,CodeCompanion.cli() 优先复用该 Agent 的既有实例(find_by_agent),否则创建新实例,这一点与文档中 “reuses an existing instance of this agent if one exists” 的描述一致。相关测试见 tests/interactions/cli/test_cli.lua。
3.2 CLI 全局选项
require("codecompanion").setup({
interactions = {
cli = {
opts = {
auto_insert = true, -- 聚焦 CLI 终端时自动进入插入模式
reload = true, -- Agent 修改磁盘文件时重载缓冲区(执行 :checktime)
},
},
},
})
| Option | Type | Default | Description |
|---|---|---|---|
auto_insert |
boolean |
false(config 默认值) |
聚焦 CLI 终端窗口时自动进入插入模式;文档配置页示例默认 true,以你配置为准 |
reload |
boolean |
true |
监听 cwd 下文件变更,并运行 :checktime 重载缓冲区 |
auto_insert 在 CLI.create 中通过 BufEnter/BufLeave 自动命令实现 startinsert/stopinsert。
3.3 Provider:终端如何运行 Agent
Provider 决定 Agent 进程如何被启动。内置的 terminal Provider 使用 jobstart() 在 Neovim 终端缓冲区中运行 Agent,见 providers/terminal.lua:
require("codecompanion").setup({
interactions = {
cli = {
providers = {
terminal = {
path = "interactions.cli.providers.terminal",
description = "Terminal CLI provider",
},
},
},
},
})
你也可以注册自定义 Provider,path 可以是 CodeCompanion 内置模块、任意 Lua 模块或文件路径:
require("codecompanion").setup({
interactions = {
cli = {
providers = {
my_provider = {
path = "my_custom.cli_provider",
description = "My custom CLI provider",
},
},
agents = {
my_agent = {
cmd = "my-cli",
args = {},
provider = "my_provider",
},
},
},
},
})
Provider 的分发逻辑在 providers/init.lua:优先使用 Agent 的 provider 字段,未匹配任何条目时回退到 terminal。
终端提供器的底层细节(对理解行为有帮助,无需配置):
- 启动时把 Agent 的
cmd作为首个元素、args作为后续元素拼成命令数组,通过jobstart(cmd, { term = true, cwd = getcwd() })启动,并注入CODECOMPANION_CLI_BUFNR、CODECOMPANION_HOOK等环境变量; - 通过轮询终端缓冲区输出的行数来判断 Agent 是否“就绪”(
MAX_WAIT = 5000ms,输出稳定 500ms 视为就绪),就绪前所有输入进入队列; - 发送队列以 100ms 间隔消费;
submit = true时在文本后追加一个回车(\r)实现“按下回车自动执行”。
四、核心工作流:从 Neovim 向 Agent 发指令
下面这些工作流通过键位映射组合,把“共享上下文 + 发送提示词”压缩成一次按键。以下示例均基于 <LocalLeader> 前缀(默认通常是 \ 或空格,视你的 leader 配置而定)。
4.1 发送自定义提示词
-- [C]odeCompanion [P]rompt
vim.keymap.set({ "n", "v" }, "<LocalLeader>cp", function()
return require("codecompanion").cli({ prompt = true })
end, { desc = "Prompt the CLI agent" })
- 普通模式下:打开提示词输入缓冲区,可先补充编辑器上下文再发送;
- 可视模式下:选区会作为上下文随提示词一并共享,省去手动指定上下文的步骤。
4.2 快速添加上下文(不打断思路)
-- [C]odeCompanion [A]dd
vim.keymap.set({ "n", "v" }, "<LocalLeader>ca", function()
return require("codecompanion").cli("#{this}", { focus = false })
end, { desc = "Add context to the CLI agent" })
#{this} 是 CLI 交互独有的上下文:普通模式解析为当前缓冲区,可视模式解析为可视选区。focus = false 保证光标不跳到 CLI 缓冲区,你可以在多个缓冲区与代码间从容挑选要共享的上下文,而不会丢失当前编辑位置。
4.3 共享 LSP 诊断并请求修复
-- [C]odeCompanion [D]iagnostics
vim.keymap.set("n", "<LocalLeader>cd", function()
return require("codecompanion").cli("#{diagnostics} Can you fix these?", { focus = false, submit = true })
end, { desc = "Send diagnostics to CLI agent" })
该键位把当前缓冲区的 LSP 诊断发送给 Agent,并借助 submit = true 自动提交(fire-and-forget),无需再手动按回车。
4.4 共享失败测试输出
-- [C]odeCompanion [T]erminal
vim.keymap.set("n", "<LocalLeader>ct", function()
return require("codecompanion").cli("#{terminal} Sharing the output from the terminal. Can you fix it?", { focus = false, submit = true })
end, { desc = "Send terminal output to CLI agent" })
#{terminal} 会共享最近一次终端会话的输出,非常适合把失败测试的堆栈信息直接交给 Agent 排查;同样使用 submit = true 自动提交。
提示:这些键位只是示例,具体按键与动作可根据你的习惯调整,核心是理解
cli()函数的入参语义(见下文 API 参考)。
五、发送上下文:更完整的用法
5.1 可视选区
可视选中一段代码后直接执行命令:
:CodeCompanionCLI Can you explain this code?
等价于 Lua:
require("codecompanion").cli({ prompt = true })
这会把可视选区传给提示词输入缓冲区,你再输入 “Can you explain this code?” 后发送。也可以硬编码提示词,跳过输入环节:
require("codecompanion").cli("Can you explain this code?")
5.2 编辑器上下文(#{...} 语法)
与 聊天缓冲区 一致,CLI 提示词同样支持编辑器上下文引用,用于共享当前 Neovim 会话的状态,例如当前缓冲区(#{buffer})、全部打开的缓冲区(#{buffers})、LSP 诊断(#{diagnostics})等。例如:
:CodeCompanionCLI Can you explain #{buffers}?
发送到 Agent CLI 后会被展开为:
❯ Can you explain the open buffers:
@your_file_path
@your_other_file_path?
Lua 侧等价写法:
require("codecompanion").cli("Can you explain #{buffers}?")
上下文的解析发生在 CLI.resolve_editor_context:它调用 editor_context:replace_cli(prompt, buffer_context) 完成替换,核心渲染逻辑分布在 interactions/shared/editor_context 下的各模块(如 buffers.lua 会把每个打开缓冲区渲染为 @相对路径)。
5.3 #{this}:CLI 独有的上下文
#{this} 是 CLI 交互特有的引用,普通模式解析为当前缓冲区路径,可视模式解析为选区代码块:
:CodeCompanionCLI What does #{this} do?
普通模式下解析为:
❯ What does @your_file_path do?
带可视选区时解析为:
❯ What does the selected code in @your_file_path do?
- Selected code from @your_file_path (lines 3-4):
````lua
local new_set = MiniTest.new_set
local T = new_set()
````
#{this} 的分流逻辑见 editor_context/this.lua:可视模式下委托给选区渲染(selection.lua),否则委托给缓冲区渲染(buffer.lua)。
[!NOTE]
@path引用可被 Claude Code、Codex 等 CLI Agent 原生识别,Agent 会直接读取对应文件,这正是 CLI 交互能高效共享上下文的关键。
5.4 提示词输入缓冲区
需要发送复杂提示词时,除了 :CodeCompanionCLI <prompt> 直传,还可以打开专用的 codecompanion_input 缓冲区:
:CodeCompanionCLI Ask
或:
require("codecompanion").cli({ prompt = true })
在该输入缓冲区中:
- 可使用全部可用的编辑器上下文(
#{...})和部分斜杠命令; - 有更大的输入空间;
- 用
:w写入缓冲区发送提示词;用:w!强制写入则在发送后立即自动提交; - 用
<up>/<down>键翻阅历史提示词。
输入缓冲区的实现在 interactions/cli/input.lua:提交回调中会先执行 resolve_editor_context 展开上下文,再复用最近实例或新建实例发送;submit_opts.bang 对应 :w! 的自动提交。
5.5 斜杠命令(Slash Commands)
提示词输入缓冲区还支持 buffer 与 file 斜杠命令,方便一次性共享大量上下文。在缓冲区中输入 / 即可调出所选 Provider 的补全菜单。
与聊天缓冲区“插入文件内容”不同,CLI 的斜杠命令插入的是 @path 引用。例如通过 /file 选择文件会插入:
@./lua/codecompanion/init.lua
选择多个文件时每个文件独占一行:
@./lua/codecompanion/init.lua
@./lua/codecompanion/config.lua
5.6 自动提交(Auto-Submit)
默认情况下,提示词会发送到 Agent 终端但不会自动按回车,文本出现在 CLI 中供你审阅后再手动回车执行。两种方式启用自动提交:
使用 bang 形式命令:
:CodeCompanionCLI! #{diagnostics} Can you fix these?
或传入 submit = true:
require("codecompanion").cli("#{diagnostics} Can you fix these?", { submit = true })
这在键位映射中尤其有用,可实现前述“诊断修复”“测试输出修复”这类 fire-and-forget 工作流。
六、Hooks:让事件系统感知 Agent 回合
CLI 交互可以与支持 hooks 的 Agent 集成,从而让 CodeCompanion 事件系统实时感知 Agent 回合的开始与结束。缺少它,依赖“回合边界”的功能(例如代码评审)将受到限制。目前 CodeCompanion 支持 Claude Code 的 hooks 集成(见 integrations/claude.lua)。
6.1 安装 hooks
在 Neovim 内执行:
:CodeCompanionCLI Install
- 对 Claude Code,hooks 会被写入
~/.claude/settings.json。
安装逻辑位于 interactions/cli/hooks.lua:它遍历配置中的所有 Agent,找到对应集成(按 cmd 名称匹配),确认其设置文件存在后弹出确认对话框,然后写入/合并 hooks 条目。Claude Code 集成会把 UserPromptSubmit、Stop、Notification、PermissionRequest、PostToolUse 等事件映射为 submitted、done、approval_requested、approval_finished 动作,并由 claude.sh 脚本通过 --remote-expr 回调 Neovim。
6.2 事件与钩子机制
这些事件经 CLI.hook 以 CodeCompanionCLISubmitted、CodeCompanionCLIDone、CodeCompanionCLIApprovalRequested、CodeCompanionCLIApprovalFinished 等形式广播,供状态栏集成、herdr 集成 等订阅使用;同时 RequestStarted / RequestFinished 事件让一次 CLI 回合在状态栏中呈现为“进行中”。需要明确的是:hooks 安装后,Agent 进程中还必须由 CODECOMPANION_HOOK 环境变量指向 hook 脚本(由 terminal Provider 注入),回调才能生效。
七、API 参考:require("codecompanion").cli()
cli() 是 CLI 交互的主要入口,具有多态签名(见 init.lua 中定义):
-- 无参数:创建新 CLI 实例并打开
require("codecompanion").cli()
-- opts 表:以选项创建新实例
require("codecompanion").cli({ agent = "claude_code" })
-- 字符串提示词:发送给最近实例(或新建一个)
require("codecompanion").cli("Can you explain this code?")
-- 字符串提示词 + 选项
require("codecompanion").cli("Fix #{diagnostics}", { submit = true, focus = false })
选项一览
| Option | Type | Default | Description |
|---|---|---|---|
agent |
string |
config 默认 | 使用的 CLI Agent;发送提示词时,若存在该 Agent 的实例则复用 |
focus |
boolean |
true |
是否打开 CLI 窗口并把光标移入;设为 false 可在后台发送上下文 |
submit |
boolean |
false |
是否自动提交(按下回车)让 Agent 立即开始工作 |
prompt |
boolean |
false |
是否打开提示词输入缓冲区而非直接发送;若同时提供字符串提示词,会预填输入框 |
width |
number |
config 默认 | 覆盖 CLI 窗口宽度 |
height |
number |
config 默认 | 覆盖 CLI 窗口高度 |
各选项的实际行为可从源码印证:
prompt = true时直接走 input.toggle 打开输入缓冲区;submit = true时在发送文本后追加\r(见 Terminal:send);focus = false时跳过ui:open与focus(),实现后台静默发送(CodeCompanion.cli());width/height会透传给 UI:open 覆盖窗口尺寸。
八、窗口布局与显示定制
CLI 窗口默认继承 display.chat.window 的布局,并可用 display.cli.window 覆盖个别项(配置合并见 UI:resolve_window_config):
require("codecompanion").setup({
display = {
cli = {
window = {
layout = "vertical",
width = 0.4,
height = 0.6,
opts = {
list = false,
},
},
},
},
})
display.cli.window 中的设置会叠加在聊天窗口默认值之上,只需指定想修改的项。也可通过 Lua API 动态传入:
require("codecompanion").cli("fix the tests", {
width = 0.5,
height = 0.8,
})
九、典型使用场景小结
| 场景 | 推荐方式 |
|---|---|
| 启动/打开 CLI 窗口 | :CodeCompanionCLI 或 require("codecompanion").toggle() |
| 发送自定义提示词 | :CodeCompanionCLI <prompt>,或用 <LocalLeader>cp 打开输入框 |
| 共享当前文件/选区 | :CodeCompanionCLI What does #{this} do? 或 <LocalLeader>ca |
| 修复 LSP 诊断 | <LocalLeader>cd(#{diagnostics} + submit = true) |
| 修复失败测试 | <LocalLeader>ct(#{terminal} + submit = true) |
| 一键自动提交 | 命令加 ! 或 Lua 传 submit = true |
| 多 Agent 切换 | :CodeCompanionCLI agent=<name> <prompt> |
| 启用事件感知 | :CodeCompanionCLI Install(写入 ~/.claude/settings.json) |
十、进一步阅读
- 完整配置项与 Agent/Provider 定义:见 doc/configuration/cli.md
- 编辑器上下文语法总览:见 doc/usage/chat-buffer/editor-context.md
- 聊天缓冲区斜杠命令:见 doc/usage/chat-buffer/slash-commands.md
- CLI 交互源码入口:interactions/cli/init.lua
- CLI 相关测试:tests/interactions/cli/test_cli.lua
适用前提说明:CLI 交互要求你的机器上已安装对应 Agent(如 Claude Code、Codex),并已在
interactions.cli.agents中完成配置;本文所述命令与行为以当前仓库源码为准。