tmux-claude-panel

基于 example/tmux_ai_coder_panel_src 改造的本地 Web 面板： 左边是 tmux 会话里跑着的 Claude Code，右边是那段会话的 jsonl 历史 + 实时屏幕 + 键盘输入。

一个进程、一个端口、零前端构建。

┌────────────────┬──────────────────────────────────────────┐
│ tmux · claude  │  e389d12e  [tmux: main] [837 行]     ⟳   │
│ 6 会话         │  ────────────────────────────────────────│
│ ▾ main ●       │   14:22  · claude-sonnet                │
│   ● e389d12e   │   ⚙ Bash · npm test                     │
│     修复播放     │   测试全过，271 个用例                    │
│   ○ bc0dca7a   │                                          │
│ ▸ tmp          │   ↑ 上滑加载更早                          │
│ ▾ 其他会话     │  ── 实时屏幕 ────────────────────────────  │
│   ○ 9c81df58   │  $ claude ...                            │
│                │  [⏎ Esc ↑ ↓ 1 2 y n Ctrl-C]              │
│                │  [输入指令…………………]  [发送]             │
└────────────────┴──────────────────────────────────────────┘

快速开始

cd panel
pip install -r requirements.txt
python -m tmux_panel                 # 127.0.0.1:20016，被占用自动 +1
# python -m tmux_panel --host 0.0.0.0   # 手机/局域网访问

两种传输，同一套帧语义

右上角小徽章显示当前是 REST 5s 还是 WS。默认就是 REST 轮询（无长连接，最省 服务端），?transport=ws 才显式开长连接；WS 连不上时前端自动降级为轮询，不需要手动切。 轮询走 GET /api/index + GET /api/state，都带 ETag： 内容没变回 304 不带 body，实测 1s × 3 客户端从 2.29 MB/min 降到 193 KB/min。

服务端省资源的机制（与协议无关，详见 ../spec/SBP-transport.md）： 共享抓屏缓存、索引只在 tick 里重建一次、tick 周期自适应（5s 轮询就按 2.5s 抓屏）、 扇出只序列化一次。诊断数据看 GET /api/stats。

首次启动会在当前目录生成 .env（随机账号密码并打印），登录后即可用。 --no-auth 可关闭登录，只在纯本机调试时用。

左侧出现会话的前提：

1. 有 tmux 会话：tmux new -s work -c ~/codes/foo
2. 该会话的工作目录里跑过 claude（~/.claude/projects/<slug>/<uuid>.jsonl 存在）

侧栏的深色 / 灰色（活跃判定）

一个 tmux 组里只有「当前正被 agent 用着」的那个会话是深黑 + 绿点，其余一律灰掉并挂 历史 角标；这个 tmux 里没跑 agent 时整组全灰。判定在 tmux_panel/live.py，三级证据：

dsh / codex 这类没有会话文件的 pty agent 同一套规则，只是证据换成进程： 按 pane 维护一条 term:<tmux>（多 agent pane 时第二个起是 term:<tmux>#<pane_id>）， 进程树里此刻还有 agent 进程 → 深黑 + 绿点，副标题取自屏幕上的 task: 行； agent 已退出（pane 只剩 shell）→ 灰色 + 未激活 角标，但仍可点开看屏幕。 纯 shell 的 pane 不进列表。判定都在 tmux_panel/live.py 的 running_agent()。

索引每 6s 重算一次，指纹（活跃 sid / 数量 / 标题）变了才向前端广播； 前端正在编辑注释时暂存推送，编辑结束再补渲染。见 panel/docs/ui_active_grey.png。

它到底做了什么

协议（SBP v0.1 子集）

信封与 spec/SBP-0.1.md 一致，WS /ws：

→ {"v":"sbp/0.1","id":"c1","type":"req","name":"sessions.index","payload":{"refresh":true}}
← {"v":"sbp/0.1","type":"res","ref":"c1","name":"sessions.index","ok":true,
   "payload":{"groups":[{"name":"main","cwd":"/Users/mac","live":true,"items":[...]}]}}

→ {"name":"session.history","sid":"e389…","payload":{"before":818,"limit":20}}
→ {"name":"session.attach","sid":"e389…"}          // 订阅增量 + 屏幕
→ {"name":"session.input","sid":"e389…","payload":{"kind":"text","text":"继续","submit":true}}
← evt session.message / output.delta / session.state

从原项目改了什么

保留：

• TmuxManager 的多 socket 解析、path_to_session_name、鉴权（HMAC cookie + ?token= 兜底）、 find_free_port / .env 自动生成 / 启动横幅 —— 这些是踩过坑的地方，直接沿用。

替换：

• Vue3 打包产物（frontend_dist，改不动）→ 换成 web/ 下无构建的三件套（html/css/js）。
• WebSocket 语义：原来是「键盘 LED 面板」事件（keypress/set_mode）， 现在是「会话流」协议（索引/分页/订阅/输入），并按 SBP 的信封规范命名。
• 新增数据层：claude.py 负责 jsonl 发现、索引、分页、增量；hub.py 负责分组与推送。

没有改 example/ 下的任何文件，两边可以并存对比。

已知边界

• 只做了 Claude Code 的 jsonl（~/.claude/projects）。换别的 agent 只需换 claude.py 的解析层。
• 子代理消息（isSidechain:true）默认不展示，避免刷屏；需要时改 normalize()。
• 一个 tmux 会话里如果切过多个 claude 会话，侧栏会把该目录下的会话全列出来（按 mtime 倒序）， 真正"当前在跑"的那个排最前并带绿点。
• jsonl 超过 8MB 时侧栏不显示条数（避免每次列表都全量扫行）；打开后仍可正常翻页。

目录

panel/
├── tmux_panel/
│   ├── tmux.py      # tmux 访问（多 socket + send-keys/capture-pane）
│   ├── claude.py    # jsonl 发现/索引/倒序分页/增量/注释
│   ├── hub.py       # 分组索引 + 1.2s 推送循环
│   ├── server.py    # FastAPI + WS 协议
│   └── __main__.py  # CLI：端口探测 / .env / 横幅
└── web/
    ├── index.html
    ├── style.css
    └── app.js