Claude Grid
Claude Grid 是一个 VS Code 扩展，用于在编辑器区域按需添加 AI Agent 终端，支持多项目目录切换和多 Agent 选择，自动完成最优布局排列。
功能
- 每次点击状态栏按钮或执行命令，添加一个新的 Agent 终端
- 支持 Claude Code、Codex CLI、Gemini CLI、OpenCode 四种 Agent
- 弹出选择器，可分别选择工作目录和 Agent（normal 模式）
- auto 模式下直接在当前工作区目录启动默认 Agent，无需任何交互
- 终端名自动显示 Agent 名称和项目名（如
Claude Code · my-project）
- 自动按终端数量应用最优布局（1、2、3、4 格），超过 4 个时在第 4 格追加
- 状态栏实时显示当前托管终端数量
- 终端关闭后自动从管理列表中移除并更新状态栏
- 只管理本扩展创建的终端，不影响其他终端
使用前提
在使用前，请确认：
- 你正在使用桌面版 VS Code
- 本机已安装你想使用的 Agent CLI（Claude Code、Codex CLI、Gemini CLI 或 OpenCode）
- 对应命令（
claude / codex / gemini / opencode）已加入系统 PATH
使用方式
状态栏
点击左下角状态栏中的 $(terminal) Claude Grid 按钮。
- 无终端时显示：
Claude Grid
- 有终端时显示：
Claude Grid (N)
命令面板
- 按
Ctrl+Shift+P
- 执行
Claude Grid: Add Claude Terminal
normal 模式（默认）
触发时弹出两个快速选择菜单：
- 选择工作目录：列出所有已打开的工作区文件夹，最后一项「浏览其他文件夹...」可选择任意目录
- 选择 Agent：Claude Code / Codex CLI / Gemini CLI / OpenCode
选好后终端将在所选目录下启动，并自动运行对应 Agent 命令。
auto 模式
无任何弹窗，直接在当前工作区第一个文件夹目录下，用默认 Agent 打开终端。
适合高频使用场景，配合 claudeGrid.defaultAgent 和键盘快捷键效果最佳。
布局规则
| 终端数量 |
布局 |
| 1 |
单列全屏 |
| 2 |
左右各一 |
| 3 |
左一 + 右上下各一 |
| 4+ |
左右各上下两个（2x2），第 5 个起追加到第 4 格 |
配置项
claudeGrid.mode
- 类型：
string
- 默认值：
normal
- 可选值：
normal | auto
- 说明：
normal：每次添加终端时弹出目录和 Agent 选择器auto：直接使用当前工作区目录和默认 Agent，不弹任何选择器
如何配置： 打开 VS Code 设置（Ctrl+,），搜索 claudeGrid.mode，或在 settings.json 中添加：
"claudeGrid.mode": "auto"
claudeGrid.defaultAgent
- 类型：
string
- 默认值：
claude-code
- 可选值：
claude-code | codex-cli | gemini-cli | opencode
- 说明：默认 Agent。auto 模式下直接使用；normal 模式下作为选择器预选项。
如何配置： 打开 VS Code 设置（Ctrl+,），搜索 claudeGrid.defaultAgent，或在 settings.json 中添加：
"claudeGrid.defaultAgent": "gemini-cli"
claudeGrid.claudeCommand
- 类型：
string
- 默认值：
claude
- 说明：发送到终端的启动命令。如需覆盖默认 Agent 命令（如使用绝对路径），可在此自定义。
claudeGrid.sendDelayMs
- 类型：
number
- 默认值：
250
- 说明：创建终端后发送命令前等待的毫秒数。
claudeGrid.terminalNamePrefix
- 类型：
string
- 默认值：
Claude Grid
- 说明：预留配置项，当前终端名称格式为「Agent名 · 项目名」。
claudeGrid.closePreviousOnReopen
- 类型：
boolean
- 默认值：
false
- 说明：再次执行命令时，是否先关闭本扩展之前创建的终端。
claudeGrid.rows / claudeGrid.cols
- 类型：
number
- 默认值：
2
- 说明：预留配置项，当前版本布局由终端数量自动决定（1→单列，2→左右，3→左一右二，4+→2x2），此项暂不生效。
claudeGrid.location
- 类型：
string
- 默认值：
editor
- 说明：终端打开位置，当前版本仅支持
editor。
推荐配置示例
全自动模式（高频使用）：
"claudeGrid.mode": "auto",
"claudeGrid.defaultAgent": "claude-code"
多项目多 Agent 模式（灵活切换）：
"claudeGrid.mode": "normal",
"claudeGrid.defaultAgent": "claude-code"
错误处理
未找到命令
- 请确认对应 CLI 工具已安装且命令可在终端中直接执行
- 或在设置中修改
claudeGrid.claudeCommand 指向实际路径
布局问题
- 请确认
claudeGrid.location 为 editor
- 可打开输出面板查看
Claude Grid 日志
开发
环境准备
git clone https://github.com/hopesy/claude-grid
cd claude-grid
npm install
编译
npm run compile
调试
按 F5 在 Extension Development Host 中启动调试，会打开一个新的 VS Code 窗口加载本扩展。
运行测试
npm test
打包为 .vsix
npm run package
产物输出到 out/claude-grid-x.x.x.vsix。
本地安装
- 打开 VS Code
- 按
Ctrl+Shift+P 执行 Extensions: Install from VSIX...
- 选择
out/ 目录下的 .vsix 文件
发布到插件市场
需要先在 Visual Studio Marketplace 注册发布者账号并获取 Personal Access Token。
# 登录（首次）
npx vsce login <publisher-name>
# 发布
npx vsce publish
或一步打包并发布：
npx vsce publish --packagePath out/claude-grid-x.x.x.vsix
发布前请确认 package.json 中 publisher 字段与你的市场账号一致。
已知限制
- 仅支持桌面版 VS Code
- 终端精确布局属于 best-effort，不同 VS Code 版本下视觉效果可能略有差异
