games-development-ai/.agents/skills/drive-remote-claude-tmux.md

name, description

name	description
drive-remote-claude-tmux	从控制机经 ssh+tmux 双向驱动远端机上交互式 Claude Code(send-keys 派活/capture-pane 读屏/专用 worktree 会话/git commit 作完成判据)时使用。⚠️ 退役候选:原前提 6c6g 大脑线已停用,去留待创始人拍;tmux 桥技术仍可复用。

远程驱动交互式 Claude Code（ssh + tmux）

用途：从控制机（6c6g 大脑线）经 ssh 进远端开发机（Mac/Linux），双向驱动跑在 tmux 里的交互式 Claude Code——派活（send-keys）+ 读屏（capture-pane）。不走 ACP、不走 claude -p headless，驱动的就是带完整上下文的交互式 TUI，创始人能同时 attach 旁观/随时夺键。 创始人 2026-06-18 拍板采用（option 1=专用会话）+ 要求多设备复用——新机器照本配方 onboarding。背景见记忆 session-division-mac-dev-6c6g-brain、internal-build-infra-servers。

---

0. 适用与边界

• 适用前提：远端开发机 ① ssh 免密可达 ② 装了 tmux ③ Claude Code 跑在 tmux 会话里（非裸 Terminal/iTerm tab）。
• 不适用：会话跑在 GUI 终端 tab 而非 tmux → ssh 够不到那个 TTY（macOS 不许跨登录会话注入按键，screen reptyr 需关 SIP）。补救=把会话迁进 tmux。
• 权威验收信号 = git push 的 commit（git fetch 侦测）。capture-pane 只为实时盯进度/答澄清，不作完成判据——读屏会骗人，commit 不会。

1. 每设备配置（加新机器只改这块）

项	示例值（lili-mac，2026-06-18 实测）
ssh 别名	lili-mac
tmux 二进制	/opt/homebrew/bin/tmux（Apple Silicon Homebrew）
仓库路径	/Users/lili/Project/games-development-ai
登录 shell	/bin/zsh
我的专用会话	auto（独立 git worktree，见 §4）

⚠️ PATH 坑（必踩）：非交互 ssh（ssh host '...'）的 PATH 不含 Homebrew → which tmux 假阴性（实测先误判"没装 tmux"）。命令前一律 export PATH=/opt/homebrew/bin:$PATH，或用 tmux 全路径。

2. Onboarding 一台新设备（侦察配方，全只读）

# ① 探活 + 找 tmux + 列会话 + 定位各 claude 进程的 cwd（哪个会话在哪个仓）
ssh <host> 'echo ===HOST===; hostname; uname -sr;
  echo ===TMUX===; ls /opt/homebrew/bin/tmux /usr/local/bin/tmux 2>/dev/null;
  echo ===SESSIONS===; /opt/homebrew/bin/tmux ls 2>/dev/null;
  echo ===CLAUDE-CWD===; for p in $(pgrep -f "[c]laude"); do lsof -a -p $p -d cwd 2>/dev/null | tail -1; done'

# ② 逐会话识别身份（只读 capture，零打扰 attached 客户端）
ssh <host> 'export PATH=/opt/homebrew/bin:$PATH;
  for s in $(tmux ls -F "#{session_name}"); do echo "== $s =="; tmux capture-pane -t "$s" -p | grep -v "^[[:space:]]*$" | tail -6; done'

辨会话靠 capture 底部状态行：Claude Code 显示 Model: Opus 4.8 | Thinking: … | Ctx: …k | ⎇ 分支 | permissions；Codex 显示 gpt-5.x xhigh · 路径 · 分支。

3. 通道原语（已实测通过）

• 派活：tmux send-keys -t <s> -l '<prompt 文本>' 再 tmux send-keys -t <s> Enter
  • 文本用 -l（literal）防止把内容里的词当按键名解析；Enter 单独发以提交。短指令可 tmux send-keys -t <s> '<text>' Enter 一行。
  • 长 prompt：先写进仓内文件，再发"读 <file> 并执行"——绕开 TUI 粘贴检测与 shell 转义地狱。
• 读屏：tmux capture-pane -t <s> -p（可 | tail -N）；回滚历史 capture-pane -p -S -200。只读、不打扰 attached 端。
• ⚠️ 不用 screen：实测这台 macOS 的 screen hardcopy 读屏=0 字节（坏的）；screen stuff 还得用真 CR（$'cmd\r'，\n/字面 \r 都不提交）。坑多——统一用 tmux。

4. 专用会话模式（创始人选定 option 1）

铁律：专用会话必须用独立 git worktree/分支，否则与创始人的活会话共用工作树 → 撞文件、撞 git index。

ssh <host> 'export PATH=/opt/homebrew/bin:$PATH; cd <repo>;
  git worktree add -B auto/<task> ../games-dev-auto origin/dev/2.0.0;
  tmux new-session -d -s auto -x 220 -y 50 -c <repo>/../games-dev-auto;
  tmux send-keys -t auto "claude --permission-mode bypassPermissions" Enter'

• --permission-mode bypassPermissions → 注入任务不卡审批弹窗（控制机看不到弹窗也答不了）。
• 创始人 tmux attach -t auto 可旁观；约定 auto 是控制机的会话，创始人只看不打字（防撞键）。

5. 操作环（派活 → 盯 → 审）

1. send-keys 一个自洽任务，末尾要求："干完 git commit + push 到 WIP 分支，然后停"。
2. 轮询 capture-pane | tail -40 看进度；卡澄清/红字才读屏后 send-keys 答（bypass 下基本无弹窗）。
3. 完成 = git push 出现 commit（git fetch <remote> <branch> 侦测），非读屏。
4. 控制机 fetch + codex/opus 审 commit → 反馈走计划/评审档 → 下一轮（见 session-division-mac-dev-6c6g-brain 的协调环）。

6. 安全红线

• 绝不往创始人活会话（如 game/game1）注入按键未经点头——同一输入会撞键，可能毁其大上下文（实测 game Ctx 210.5k）正在干的活。capture-pane 只读可随时。
• 别碰别项目会话（如 oh-my-muse 的 muse/muse1）。
• 注入 = 在创始人机器上花其 token/quota；无明确派活不空跑。
• tmux server / 远端机 重启或休眠 → 会话丢；桥非持久，用前先 tmux ls 探活。
• 构建/测试/e2e 门仍只认 mini-desktop（x86 同构）；Mac 产 JAR/前端 bundle 架构中立可用，但 Docker 镜像+冒烟门留 mini-desktop（见 internal-build-infra-servers）。
• 多设备扩展：每台加一行 §1 配置 + 跑 §2 侦察即接入；§3 原语通用。

7. 实战限制与坑（2026-06-18 驱动 game 真踩 · 直驱活会话撞两墙）

直驱创始人活会话这条路撞了两堵墙；实务上优先「创始人粘路径(A)」或「专用全新会话(B)」，别硬刚活会话。

• 坑1 · 安全分类器拦活会话注入：即便创始人会话内点选授权（“1”/“A”），auto-mode classifier 在执行层仍反复拦 send-keys 进其活会话（连 Escape 都拦），咬住 §6 红线。口头授权不够 → 要设置层 Bash 权限规则（如 Bash(ssh lili-mac:*)），且拦得非确定（有的 send 过了又升级再拦）。
• 坑2 · 反馈模态吃键：活会话完工常挂 “How is Claude doing this session?” 模态（1/2/3/0）。它截获所有非选项键——实测 Escape/C-u/60×BSpace 全被吃、输入框纹丝不动（草稿清不掉、/clear 也进不去）。须先 0 关模态（但关模态本身可能被坑1拦）。
• 坑3 · 近满上下文：game Ctx 884k 时塞新活易触发 compact，贵且慢；系统会提示 /clear。
• 行得通三条路（择一）：
  • A · 创始人粘路径（本会话最终成功）：指令写文件 + scp 到 Mac /tmp/xxx.md → 创始人手动清模态/草稿 + 粘 读 /tmp/xxx.md 并按其执行。零 guard 摩擦。
  • B · 专用全新会话：独立 worktree 起 fresh claude --permission-mode bypassPermissions（无模态/无 884k/非活会话）→ 大概率不触坑1。
  • C · 直驱活会话：须 ① 创始人加 Bash 权限规则 ② 先 0 关模态+清草稿。最脆，仅当必须复用其上下文时。
• 铁律重申：完成判据 = git push 的 commit（本会话 Mac 推 6a9bd4d3 → 我 fetch + 审 + 集成全靠 git，零依赖读屏）；capture-pane 只读盯状态。