wtx

带内置 MCP 服务器的 Git 工作树管理器。 从终端创建、检查并清理隔离工作区——或者让你的 AI 编码智能体自己完成。

并行 AI 编码智能体让 git stash 这种手动切换方式变得过时，但 git worktree add ../foo -b foo && cd ../foo && cp ../.env . 这样一遍遍敲的命令，显然是没人想每天重复五次的事情。wtx 把工作树变成“一个词”的工作流，对人和智能体都好用：

$ wtx new fix-login
✔ created worktree fix-login
  path:   ~/code/myapp/.worktrees/fix-login
  branch: wt/fix-login (new)
  copied: .env, .env.local

你的智能体可以通过 MCP 获得同样的能力：

{ "name": "create_worktree", "arguments": { "name": "fix-login", "setup": "npm install" } }

为什么选择 wtx

• 一个工具，两种接口。 供你使用的快速 CLI，为 Claude Code、Cursor、Codex 或任何支持 MCP 的智能体提供 MCP 服务器（wtx mcp）。

• 零依赖。 只调用 git 的单个 Node.js 可执行程序。没有可审计的东西，也没有容易出错的依赖。

• 整洁管理。 每个工作树都显示磁盘占用和最近活动时间。用 wtx clean --dry-run 可以清理大量过时的 node_modules 克隆，释放大量空间。

• 默认安全。 拒绝删除 dirty 的工作树，绝不触碰主检出，只在完全合并后删除分支，并通过 .git/info/exclude 隐藏 .worktrees/（不会污染 .gitignore）。

• 开箱即用。 可将 env 文件复制到新工作树，并自动运行项目的 setup 钩子。

安装

npm install -g wtx        # or: brew install wtx (planned)

需要 Node.js ≥ 18 以及任意现代 git。

快速上手

$ cd myapp
$ wtx new feat-search          # isolated workspace at .worktrees/feat-search on branch wt/feat-search
$ cd $(wtx path feat-search)   # jump in
$ wtx ls                       # see every workspace, its state and size
NAME       BRANCH         STATUS       AGE      SIZE     PATH
myapp*     main           ✓ clean      2d ago   412 MB   ~/code/myapp
feat-api   wt/feat-api    ● dirty (1)  3h ago   38 MB    ~/code/myapp/.worktrees/feat-api
$ wtx clean --dry-run          # preview reclaimable space
· feat-api (branch merged, 38 MB)
would free: 38 MB · kept 0 worktree(s)

命令

全局标志：--json（机器可读输出）、--base <ref>、--setup <cmd>、--no-copy、--no-setup。

在 AI 智能体中使用（MCP）

添加到 MCP 客户端配置：

// e.g. claude_desktop_config.json / opencode.json / .mcp.json
{
  "mcpServers": {
    "wtx": { "command": "npx", "args": ["-y", "wtx", "mcp"] }
  }
}

服务器暴露四个工具：list_worktrees、create_worktree、remove_worktree、clean_worktrees。它们都可以接受一个可选的 repo_path；否则使用服务器的当前工作目录。返回的是 JSON，所以智能体可以通过链式方式完成：create → work → remove，不需要在主 checkout 中切换分支。

示例智能体提示词：“基于 develop 分支创建一个名为 oauth-fix 的工作区，在其中运行 pnpm install，然后告诉我它的路径。”

配置

在仓库根目录中放一个 wtx.config.json（或 .wtxrc）：

{
  "dir": ".worktrees",
  "copyFiles": [".env", ".env.local"],
  "setup": "pnpm install",
  "branchPrefix": "wt/"
}

安全模型

• 主工作树永远不会被 rm 或 clean 删除。

• clean 始终保留 dirty 的工作树；rm 则需要 --force。

• 分支只会在完全合并到默认分支（origin/HEAD → main → master 回退）后才被删除。

• 工作树目录都位于 .worktrees/ 下，通过 .git/info/exclude 排除，所以不会碰你的 .gitignore。

• 名称会经过检测，像 ../evil 这类目录穿越会被拒绝。

它与其他方案的对比

开发

git clone https://github.com/willkhinz/wtx && cd wtx
npm install
npm test        # build + 32 integration/unit tests
node dist/src/cli.js help

架构：src/core.ts（引擎）、src/cli.ts（人类界面）、src/mcp.ts（智能体界面）。MCP 实现是零依赖的行分隔 JSON-RPC 2.0。

路线图

• wtx exec <name> -- <cmd> 在所有工作树中执行命令

• 每个工作树 spawn 一个 tmux/iTerm 会话

• Homebrew formula

• GitHub Action：在 PR 中评论各个工作树的预览

许可证

MIT