---
name: drive-remote-claude-tmux
description: "从控制机经 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 一台新设备（侦察配方，全只读）

```bash
# ① 探活 + 找 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。

```bash
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` 只读盯状态。