Worktree Map

Codex 桌面端插件：在当前仓库里查看分支家谱 + worktree 工位，标出当前会话位置，并支持创建、谨慎删除、安全清理与会话跳转（含降级指引）。

交付形态：Skills + 本地 MCP（stdio）+ MCP App UI（对话内面板）。

演示

Personal marketplace 安装后，在任意仓库会话里打开关系图：

仓库总览：分支家谱、worktree 工位与当前会话标记：

分支操作：新建子分支、新建 worktree、一并创建：

Related MCP server: git-insights-mcp

要求

• Node.js 20+

• pnpm 9（可用 Corepack）

• 本机 git

安装（Codex 本地 marketplace）

在本仓库根目录：

corepack enable
corepack prepare pnpm@9.15.0 --activate
pnpm install
pnpm build

仅在本仓库会话可用（repo marketplace）

仓库内已有 .agents/plugins/marketplace.json（path: ./）。

1. 把 Codex 会话 cwd 设为本仓库根。

2. 重启 Codex，打开 Plugins，安装 Worktree Map。

在任意仓库可用（推荐：personal marketplace）

Repo marketplace 不会跟着你进别的项目。要在其他仓库用，需装到个人 marketplace：

mkdir -p ~/.agents/plugins ~/.codex/plugins
ln -sfn /Users/apple/Desktop/worktree_map ~/.codex/plugins/worktree-map

写入 ~/.agents/plugins/marketplace.json（若已有其它插件，把下面这条合并进 plugins 数组）：

{
  "name": "personal",
  "plugins": [
    {
      "name": "worktree-map",
      "source": {
        "source": "local",
        "path": "./.codex/plugins/worktree-map"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Developer Tools"
    }
  ]
}

然后：

1. 完全退出并重启 Codex。

2. 任意打开一个 git 仓库会话 → Plugins → 安装 / 启用 Worktree Map。

3. 调用时让 session_cwd = 当前会话所在仓库的绝对路径（不是插件源码目录）。

MCP 由 .mcp.json 经 /bin/bash scripts/run-mcp.sh 启动（Codex 桌面端 PATH 通常没有 nvm 的 node，脚本会优先用 ChatGPT 自带 Node）。真正入口是自包含包 packages/mcp-server/dist/mcp.mjs（避免插件缓存里 pnpm 链接损坏）。

更新后请 pnpm build，再在 Plugins 里对 personal 版 Worktree Map 卸载 → 安装（版本会升到缓存新目录）。不要同时依赖未安装的 local-repo 副本；跨仓库用 personal 即可。改完后新开会话再试（旧会话可能仍挂着坏掉的 MCP 客户端）。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build

常用命令：

pnpm test          # core / mcp-server / ui 测试 + 插件清单校验
pnpm accept        # 规格 §10 成功标准脚本化验收（临时 git 仓）
pnpm dev:ui        # UI 开发服务器（可加 ?fixture=1）
pnpm dev:mcp       # 构建并以前台方式启动 MCP stdio 进程

包结构：

规格与分步计划见 docs/superpowers/。

插件文件

端到端验收（规格 §10）

一键门禁（单测 + 类型检查 + 构建 + §10 脚本验收）：

pnpm verify

或分步：pnpm test && pnpm typecheck && pnpm build && pnpm accept。

成功标准对照：

桌面端仍需你本地确认：Plugins 安装 → @Worktree Map → 双页签面板可渲染。

计划原文：docs/superpowers/plans/worktree-map/14-端到端验收.md。