Claude Grid

Claude Grid 是一个 VS Code 扩展，用于在编辑器区域按需添加 AI Agent 终端，支持多项目目录切换、多 Agent 选择，以及基于 Git worktree 的隔离工作目录，自动完成最优布局排列。

功能

• 每次点击状态栏按钮或执行命令，添加一个新的 Agent 终端
• 支持 Claude Code、Codex CLI、Gemini CLI、OpenCode 四种 Agent
• normal 模式下弹出选择器，可分别选择工作目录和 Agent
• auto 模式下直接在当前工作区目录启动默认 Agent，无需任何交互
• worktree 模式下自动在当前 Git 仓库创建独立 .worktrees/... 工作树，再选择 Agent
• worktree-auto 模式下自动在当前 Git 仓库创建独立 .worktrees/... 工作树，并直接使用默认 Agent
• worktree 模式自动确保 .worktrees/ 被写入 .gitignore
• worktree 模式只要求当前目录位于 Git 仓库中；即使主工作树已有未提交改动也可继续创建
• 终端名自动显示 Agent 名称和项目名；worktree 模式额外带上 worktree 短名
• 自动按终端数量应用最优布局（1、2、3、4 格），超过 4 个时在第 4 格追加
• 状态栏实时显示当前托管终端数量
• 终端关闭后自动从管理列表中移除并更新状态栏
• 只管理本扩展创建的终端，不影响其他终端

使用前提

在使用前，请确认：

1. 你正在使用桌面版 VS Code
2. 本机已安装你想使用的 Agent CLI（Claude Code、Codex CLI、Gemini CLI 或 OpenCode）
3. 对应命令（claude / codex / gemini / opencode）已加入系统 PATH
4. 若使用 worktree / worktree-auto，当前工作目录必须位于 Git 仓库中

使用方式

状态栏

点击左下角状态栏中的 $(terminal) Claude Grid 按钮。

• 无终端时显示：Claude Grid
• 有终端时显示：Claude Grid (N)

命令面板

1. 按 Ctrl+Shift+P
2. 执行 Claude Grid: Add Claude Terminal

normal 模式（默认）

触发时弹出两个选择步骤：

1. 选择工作目录：列出所有已打开的工作区文件夹，最后一项「浏览其他文件夹...」可选择任意目录
2. 选择 Agent：Claude Code / Codex CLI / Gemini CLI / OpenCode

选好后终端将在所选目录下启动，并自动运行对应 Agent 命令。

auto 模式

无任何弹窗，直接在当前工作区第一个文件夹目录下，用默认 Agent 打开终端。

适合高频使用场景，配合 claudeGrid.defaultAgent 和键盘快捷键效果最佳。

worktree 模式

无目录选择弹窗。触发后会：

1. 读取当前工作区目录对应的 Git 仓库
2. 直接使用当前 Git 仓库和当前分支 HEAD 创建新工作树
3. 自动创建 .worktrees/<MMdd-HHmm> 工作树（同分钟冲突自动追加 -2/-3）
4. 自动确保仓库根 .gitignore 含 .worktrees/
5. 弹出 Agent 选择器
6. 在新 worktree 目录中打开终端并启动所选 Agent

worktree-auto 模式

与 worktree 相同，但不弹 Agent 选择器，而是直接使用 claudeGrid.defaultAgent。

适合你明确希望“每次都开隔离工作树，并直接进默认 Agent”的场景。

布局规则

配置项

claudeGrid.mode

• 类型：string
• 默认值：normal
• 可选值：normal | auto | worktree | worktree-auto
• 说明：
  • normal：每次添加终端时弹出目录和 Agent 选择器
  • auto：直接使用当前工作区目录和默认 Agent，不弹任何选择器
  • worktree：自动创建 Git worktree，并弹出 Agent 选择器
  • worktree-auto：自动创建 Git worktree，并直接使用默认 Agent

如何配置： 打开 VS Code 设置（Ctrl+,），搜索 claudeGrid.mode，或在 settings.json 中添加：

"claudeGrid.mode": "worktree"

claudeGrid.defaultAgent

• 类型：string
• 默认值：claude-code
• 可选值：claude-code | codex-cli | gemini-cli | opencode
• 说明：
  • auto 与 worktree-auto 模式下直接使用
  • normal 与 worktree 模式下作为选择器预选项

如何配置： 打开 VS Code 设置（Ctrl+,），搜索 claudeGrid.defaultAgent，或在 settings.json 中添加：

"claudeGrid.defaultAgent": "gemini-cli"

claudeGrid.sendDelayMs

• 类型：number
• 默认值：250
• 说明：创建终端后发送命令前等待的毫秒数。

推荐配置示例

全自动当前目录模式：

"claudeGrid.mode": "auto",
"claudeGrid.defaultAgent": "claude-code"

自动 worktree + 手选 Agent：

"claudeGrid.mode": "worktree",
"claudeGrid.defaultAgent": "claude-code"

自动 worktree + 默认 Agent：

"claudeGrid.mode": "worktree-auto",
"claudeGrid.defaultAgent": "codex-cli"

错误处理

未找到命令

• 请确认对应 CLI 工具已安装且命令可在终端中直接执行

worktree 模式不可用

可能原因：

• 当前目录不是 Git 仓库
• 当前分支无法识别
• Git worktree 创建失败

遇到这类情况时，扩展会直接报错，不会回退为普通 auto 模式。

布局问题

• 可打开输出面板查看 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。

本地安装

1. 打开 VS Code
2. 按 Ctrl+Shift+P 执行 Extensions: Install from VSIX...
3. 选择 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 版本下视觉效果可能略有差异
• worktree / worktree-auto 仅适用于 Git 仓库
• worktree / worktree-auto 只要求当前目录位于 Git 仓库中
• 当前版本不会自动清理旧 worktree，也不会自动 merge/cherry-pick 回主分支