Treehouse Worktree

树屋工作台🌲

为并行AI代理工作流设计的跨平台git工作树管理器。支持CLI和MCP（模型上下文协议）接口。

](https://www.npmjs.com/package/treehouse-worktree)  ](https://nodejs.org)

为什么是树屋？

当多个AI代理需要同时在同一个存储库上工作时，git工作树提供了隔离的工作目录，而没有多个克隆的开销。Treehouse通过以下方式简化了工作台管理：

• 代理协调 -锁定工作树以防止代理之间的冲突
• 自动设置 -创建工作树时运行安装命令
• MCP支持 -通过模型上下文协议与人工智能工具集成
• 光标兼容性 -与合作 .cursor/worktrees.json 配置格式

快速开始

# Install globally
npm install -g treehouse-worktree

# Initialize in your repo
cd your-repo
treehouse init

# Create a worktree for an agent
treehouse create feature-api --agent claude-1

# List all worktrees
treehouse list

# Complete and merge work
treehouse complete feature-api --merge

# Remove when done
treehouse remove feature-api

安装

# npm
npm install -g treehouse-worktree

# Or run directly with npx
npx treehouse-worktree init

CLI命令

基本操作

# Initialize configuration
treehouse init

# Create a new worktree
treehouse create  [branch]
treehouse create feature-api              # uses 'feature-api' as branch
treehouse create agent-1 feature/new-api  # uses custom branch name

# List all worktrees
treehouse list

# Get status
treehouse status                  # all worktrees
treehouse status feature-api      # specific worktree

# Remove a worktree
treehouse remove 
treehouse remove feature-api --force  # force remove with uncommitted changes

代理商协调

# Create and lock for an agent
treehouse create feature-api --agent claude-1 --message "Working on API endpoints"

# Lock an existing worktree
treehouse lock feature-api --agent claude-2 --expiry 120

# Unlock a worktree
treehouse unlock feature-api

完成工作

# Just mark as complete (no merge)
treehouse complete feature-api

# Merge into current branch
treehouse complete feature-api --merge

# Squash merge with custom message
treehouse complete feature-api --merge --squash --message "Add new API endpoints"

# Merge and delete branch
treehouse complete feature-api --merge --delete-branch

# Merge into specific branch
treehouse complete feature-api --merge --target main

冲突解决

# Check for conflicts
treehouse conflicts
treehouse conflicts feature-api  # in specific worktree

# Resolve conflicts
treehouse resolve --ours         # keep current branch changes
treehouse resolve --theirs       # accept incoming changes
treehouse resolve feature-api --theirs

# Abort merge
treehouse abort
treehouse abort feature-api

维护

# Prune orphaned worktree entries
treehouse prune

# Clean old worktrees (based on config)
treehouse clean --dry-run   # preview
treehouse clean             # actually remove

配置

创建 treehouse.json 在您的存储库根目录中（或使用 .cursor/worktrees.json 光标兼容性）：

{
  "dir": "../worktrees",
  "defaultTargetBranch": "current",
  "lockExpiryMinutes": 60,
  "setup-worktree": [
    "npm install",
    "cp \"$ROOT_WORKTREE_PATH/.env\" .env"
  ],
  "worktree.cleanup.enabled": true,
  "worktree.cleanup.retentionDays": 7,
  "worktree.cleanup.maxSizeGB": 10
}

配置选项

设置命令

安装命令支持：

• 评论：以开头的行 # 被跳过
• 环境变量: ROOT_WORKTREE_PATH 环境变量包含主仓库路径
• 脚本文件：指向外部脚本而不是内联命令

使用环境变量的示例：

{
  "setup-worktree": [
    "npm install",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

{
  "setup-worktree-unix": ".cursor/setup.sh",
  "setup-worktree-windows": ".cursor/setup.ps1"
}

MCP集成

Treehouse包括一个MCP服务器，用于与Claude等人工智能工具集成。

设置

添加到MCP配置中：

{
  "mcpServers": {
    "treehouse": {
      "command": "treehouse-mcp"
    }
  }
}

或者使用npx：

{
  "mcpServers": {
    "treehouse": {
      "command": "npx",
      "args": ["treehouse-worktree", "mcp"]
    }
  }
}

可用的MCP工具

多代理工作流示例

# Agent 1 starts working on API
treehouse create api-work --agent agent-1 --message "Implementing REST endpoints"

# Agent 2 starts working on UI (different worktree)
treehouse create ui-work --agent agent-2 --message "Building dashboard components"

# Check what's being worked on
treehouse list

# Agent 1 finishes and merges
treehouse complete api-work --merge --delete-branch
treehouse remove api-work

# Agent 2 finishes
treehouse complete ui-work --merge
treehouse remove ui-work

程序化使用

import { treehouse } from 'treehouse-worktree';

// Create a worktree
const result = await treehouse.create({
  name: 'feature-api',
  agentId: 'my-agent',
  lockMessage: 'Working on API'
});

// List worktrees
const list = await treehouse.list();

// Complete work
await treehouse.complete({
  name: 'feature-api',
  merge: true,
  deleteBranch: true
});

配置文件搜索顺序

Treehouse按以下顺序查找配置：

1. .cursor/worktrees.json 在当前工作台上
2. treehouse.json 在当前工作台上
3. .cursor/worktrees.json 在repo根目录中
4. treehouse.json 在repo根目录中

需求

• Node.js 18+
• Git 2.5+（支持工作台）

故障排除

常见问题

“Git不可用”

• 解决方案：安装git并确保它在你的PATH中
• 通过以下方式进行验证： git --version
• Treehouse要求2.5或更高

“不在git存储库中”

• 解决方案：运行 git init 首先，或导航到现有的git存储库
• 请检查： git status

“工作树已存在”

• 解决方案：请选择其他名称或先删除现有工作台
• 列出工作树，包括： treehouse list
• 删除： treehouse remove

“工作树有未提交的更改”

• 解决方案：在移除/完成工作台之前提交或隐藏更改
• 使用 --force 无论如何都要删除的标志（警告：将丢失更改）

Windows上的安装命令失败

• 解决方案：使用特定于平台的设置命令
• 集 setup-worktree-windows 在您的配置中
• 确保PowerShell或cmd命令的格式正确

锁已过期，但工作台仍显示为已锁定

• 解决方案：手动解锁 treehouse unlock
• 锁自动过期基于 lockExpiryMinutes 配置

元数据与实际工作树不同步

• 解决方案：运行 treehouse prune 清理孤立的条目
• 这将元数据与实际的git工作树同步

获取帮助

• 检查
• 阅读 贡献指南
• 查看 更新日志 最近的变化

许可证

麻省理工学院