tmux-worktree-session

tmux Worktree 会话

搭建一个独立的工作区：隔离的 git worktree、用于操作它的 tmux 会话、正在运行的开发栈，以及已开始处理任务简报的新 Agent。 人类连接会话时，工作已经开始推进。

组合两项技能：用于安全操作窗格的 tmux-orchestration，以及用于撰写简报的 handoff。

标准布局

Session: <Project>-<work>     (hyphenated, no spaces)
├── Window 1 "agent" → coding agent (Claude/Codex), cwd = worktree, given a
│                      kickoff prompt pointing at the briefing
├── Window 2 "cli"   → bare shell for tests and ad-hoc commands
└── Window 3 "dev"   → dev stack

三个窗口，各司其职，不拆分窗格。这是常见布局；按需调整（没有开发栈、两个 Agent、增加日志窗口）。若情况不明，请确认。除非用户要求，否则不要添加 git/lazygit 窗口。

输入

根据上下文填写，不要反复询问：

• 工作名称 → 分支名 + 会话名。如果有 PR/issue 编号，优先使用。
• Agent + 模式 → Claude 或 Codex、fast/plan。不确定时询问一次。
• 基础分支 → 通常是默认分支；worktree 工具通常以 origin/<default> 为基础，这会影响步骤 1。

流程

1. 撰写简报，并先将其提交到基础分支

使用 handoff 撰写 Agent 要读取的内容：任务目标、范围明确的任务、文件/模式、惯例和限制。简报应说明任务，而非记录历史。

如果 worktree 工具以 origin/<default> 为基础创建新工作树，应先将简报提交并推送到基础分支，再创建 worktree，否则 Agent 看不到简报。

2. 找到并运行 worktree 工具

先查找（见速查表），不要想当然。常见命令：bin/worktree create <name>、bin/worktree create --pr 42。备用方案：git worktree add ../<repo>-<branch> -b <branch> origin/<default>。

创建过程通常会触发完整引导（依赖项、数据库、密钥），耗时可能长达几分钟，不要以为它卡住了。过程中可能会提示输入密钥（1Password、主密钥、环境令牌）：这需要由用户批准，请提示用户并等待，切勿自行输入凭据。在可见窗格中运行，并等待明确的完成信号（追加 ; echo DONE_$? 并轮询），之后再启动开发栈。

3. 找到开发栈和测试命令

先查找（见速查表）。优先选择适合你控制的无头/分离模式（例如 process-compose -D + status/logs）；也可以使用前台 TUI 供人查看。记下测试运行器，cli 窗口和 Agent 都需要它。

4. 构建会话

通过 tmux-orchestration 处理具体操作。以下细节容易出错：

• 分离模式创建会话，避免影响用户当前会话。
• 使用连字符命名，不要有空格。
• 窗口 1 agent：切换到 worktree 目录，启动 Agent；其界面就绪后，使用缓冲粘贴发送启动消息，然后单独执行 Enter。消息应简短，指向简报。也可以将同级窗格的 ID（cli、dev）交给它，让它通过 tmux CLI 自行轮询。
• 窗口 2 cli：切换到 worktree 目录，保留一个普通 shell，用于运行测试和临时命令。
• 窗口 3 dev：切换到 worktree 目录，运行开发栈。

每个窗口都要切换到 worktree 目录，并确保使用正确的工具链（见版本管理器注意事项）。

5. 验证并报告

• 确认开发栈实际健康（轮询 status/健康状态），而不只是“已启动”；若有任何故障，请查看进程日志。
• 确认 Agent 实际已启动（捕获其窗格内容，不要假设粘贴成功）。
• 报告：tmux attach -t <session>。

注意事项

版本管理器不会在派生的 shell 中激活（最重要的一点）。 以编程方式启动的 shell（tmux new-session，非登录 shell）通常不会加载用户的版本管理器（mise/asdf/rbenv/nvm），因此 ruby/node/python 会悄悄回退到系统版本，导致引导失败（例如 "Could not find bundler"）。

• 检查：比较你所在窗格与用户环境中的 ruby -v 等输出。结果不一致就是问题的迹象。
• 修复交互式窗格：将 shims 加入 PATH，例如 mise 的 export PATH="$HOME/.local/share/mise/shims:$PATH"。
• 同时修复开发栈的子进程：每条需要使用 mise 管理的工具的命令都运行 eval "$(mise activate bash)" && …（或 mise exec --）。

窗格机制与安全性 → tmux-orchestration。 窗格 ID 定向、绝不向自己的窗格写入、先读后写、粘贴多行提示词缓冲区、将 Enter 作为单独一步——这些内容都在其中。不要在此重复；请遵循其说明。这里值得重申两点：会话名称中不能有空格（session:window 目标会被错误解析），并且要用程序自身的按键退出开发 TUI（process-compose 使用 F10），不要猜测使用 Ctrl-C。

快速查找指南

需求	查找内容
Worktree 工具	bin/worktree、script/worktree、DEVSTACK.md、just/make，否则使用 git worktree add
开发栈	bin/dev、npm/pnpm dev、foreman/overmind、process-compose、docker compose、mise run dev、项目命令
测试运行器	bin/rspec、pnpm test、pytest、go test、Makefile
工具链	.mise.toml/.tool-versions/.ruby-version/.nvmrc — 确认派生的 shell 使用了它