kunchenguid/treehouse

它解决了什么问题

Treehouse 管理一个可重用的、隔离的 git worktree 池，从而消除了手动处理同一个仓库的多个克隆版本或为每个 AI agent 会话创建新 worktree 的需求。它能防止 agent 之间发生冲突，并确保依赖项和构建缓存可以在会话之间保留，从而加快 agent 的执行速度。

工作原理

Treehouse 在配置的根目录（默认为 ~/.treehouse/）中维护一个 worktree 池。当用户或 agent 请求一个 worktree 时，Treehouse 会扫描池中是否有空闲、干净且可重用的 worktree。如果找到了，它会将该 worktree 重置为最新的默认分支；否则，它会以 detached HEAD 模式创建一个新的 worktree。

关键机制包括：

• Subshell Access：用户会被带入 worktree 内的一个 subshell 中；退出 shell 后，worktree 会返回到池中。
• Durable Leases：worktree 可以被租用以进行持久使用，而无需运行长寿命进程，这需要通过显式的返回命令来回收。
• In-use Detection：该工具会扫描运行中的进程和预留情况，以确保在 worktree 处于活动状态时不会将其分配出去。
• Safety Checks：修剪（Pruning）和销毁 worktree 默认采用 dry-run 模式，并且除非使用了特定的覆盖标志，否则只会移除干净且已合并到默认分支的 worktree。

适用人群

需要为同一个项目提供多个隔离环境，但又不想承担克隆开销或丢失构建缓存的开发者和 AI agent 运营者。

亮点

• Instant Isolation：快速进入一个干净的 worktree，无需手动设置。

• Reusable Environments：保留依赖项和构建缓存，以避免冗余安装。

• Conflict-Free：自动检测正在使用的 worktree，防止 agent 之间互相干扰。

• Safe Management：稳健的修剪机制、对孤儿 worktree 的清理以及对损坏的池状态文件的状态恢复能力。