treeman

treeman

当多个 Agent 同时在同一个仓库中工作时，每个 Agent 通常都会有自己的 git worktree。过一段时间后，就没人记得每个 worktree 属于谁、哪些仍有未提交的工作，以及哪些可以安全删除。treeman 根据你已有的信息回答这些问题。对于每个 worktree，你提供它的路径、其中检出的分支、所有者（如果有）、是否有未提交的更改、自上次更改以来经过的天数，以及它是否已锁定；此外，还要提供超过该天数后就视为过时的不活动阈值，并可选提供主 worktree 的路径。treeman 会返回计划：所有权映射、每个 worktree 的状态和清理操作，以及统计数据。它不会运行 git，也不会触碰文件系统；它只根据提供的信息制定计划。

每个 worktree 都会按照一组固定的检查进行判断，先匹配到的检查优先。路径与提供的 main_path 相同的 worktree 状态为 main，并始终保留。已锁定的 worktree 状态为 locked，并予以保留。有未提交更改的 worktree 状态为 blocked，并予以保留——绝不会计划清除未提交的更改。既超过过时阈值又没有所有者的 worktree 状态为 orphaned，这是唯一会被计划删除的类型。超过阈值但有所有者的 worktree 状态为 stale，并标记为待审核；近期活动但未记录所有者的 worktree 状态为 unowned，同样需要审核；有所有者且近期活跃的 worktree 状态为 active，并予以保留。过时判断使用严格的大于比较：上次活动时间恰好是 stale_days 天前的 worktree 不算过时。

所有权判断有一项固定规则：所有者缺失、为空或仅包含空白字符时，表示该 worktree 没有所有者，结果中的所有者报告为 null。结果中的 owners 映射会列出其他所有者及其拥有的路径，路径顺序与输入顺序一致，所有者键按升序排列；无所有者的 worktree 不会出现在其中。统计数据包括总数、每种状态的数量，以及 removable——计划标记为 remove 的 worktree 数量。

格式错误的输入——包括 worktree 列表缺失或为空、path 或 branch 缺失、为空或不是字符串、owner 不是字符串、dirty 缺失或不是布尔值、locked 不是布尔值、天数为负数或小数、stale_days 无效，或 main_path 为空——会导致验证错误，并指出有问题的路径，不会返回部分结果。两个 worktree 使用相同路径时，会报错并指出重复路径。未知的额外字段会被忽略。

CLI

npx @reneturcios/treeman plan --input args.json
npx @reneturcios/treeman --version

args.json 包含完整的参数对象：

{
  "worktrees": [
    {
      "path": "/trees/main",
      "branch": "main",
      "owner": "alice",
      "dirty": false,
      "last_activity_days": 0
    },
    {
      "path": "/trees/old-experiment",
      "branch": "exp/spike",
      "dirty": false,
      "last_activity_days": 74
    },
    {
      "path": "/trees/agent-2",
      "branch": "feat/search",
      "owner": "agent-2",
      "dirty": true,
      "last_activity_days": 1
    }
  ],
  "stale_days": 30,
  "main_path": "/trees/main"
}

计划以 JSON 格式打印：

{
  "worktrees": [
    {
      "path": "/trees/main",
      "branch": "main",
      "owner": "alice",
      "status": "main",
      "cleanup": "keep",
      "reason": "primary worktree"
    },
    {
      "path": "/trees/old-experiment",
      "branch": "exp/spike",
      "owner": null,
      "status": "orphaned",
      "cleanup": "remove",
      "reason": "no owner and inactive beyond the stale threshold"
    },
    {
      "path": "/trees/agent-2",
      "branch": "feat/search",
      "owner": "agent-2",
      "status": "blocked",
      "cleanup": "keep",
      "reason": "uncommitted changes present"
    }
  ],
  "owners": {
    "agent-2": ["/trees/agent-2"],
    "alice": ["/trees/main"]
  },
  "counts": {
    "total": 3,
    "main": 1,
    "locked": 0,
    "blocked": 1,
    "orphaned": 1,
    "stale": 0,
    "unowned": 0,
    "active": 0,
    "removable": 1
  }
}

退出代码：成功时为 0，运行时错误时为 1（包括输入文件不可读或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/treeman mcp

MCP 客户端配置：

{
  "mcpServers": {
    "treeman": {
      "command": "npx",
      "args": ["-y", "@reneturcios/treeman", "mcp"]
    }
  }
}

工具

• plan_worktrees — 根据调用方提供的工作树信息，规划并行 Agent 的 Git 工作树： 所有权映射、每个工作树的状态，以及哪些工作树可以安全移除。

  • worktrees（数组，必填，至少 1 项）— 待规划的工作树，按调用方提供的顺序排列；每项包含：
    • path（字符串，必填，非空）— 工作树路径
    • branch（字符串，必填，非空）— 工作树当前检出的分支
    • owner（字符串，可选）— 拥有该工作树的 Agent 或人员；缺省、为空或仅包含空白字符时表示无人拥有
    • dirty（布尔值，必填）— 工作树是否有未提交的更改
    • last_activity_days（整数，必填，至少为 0）— 距工作树上次更改的天数
    • locked（布尔值，可选）— 工作树是否已锁定；缺省表示 false
  • stale_days（整数，必填，至少为 0）— 不活动天数阈值；超过该阈值时工作树视为陈旧（恰好达到该值时不视为陈旧）
  • main_path（字符串，可选）— 主工作树的路径，不会被清理

  返回 {worktrees, owners, counts}，其中 worktrees 按输入顺序为每个输入工作树保存一项 {path, branch, owner, status, cleanup, reason}（无人拥有时，owner 为 null），owners 将每个不同的所有者映射到其路径，counts 为 {total, main, locked, blocked, orphaned, stale, unowned, active, removable}。

Docker

docker run -i ghcr.io/cloudcorprecords/treeman
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/treeman plan --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios