Skip to content
ztllllPublic

About

Telegram/飞书 ↔ tmux AI CLI 双向桥:精确 topic/thread 路由到 Claude Code、Codex、Pi 交互 TUI,支持 WebUI、附件与 systemd

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

tmuxbot

License: MIT Python 3.10+ Version CI

CI 状态说明: 当前 GitHub-hosted jobs 若显示未启动,仓库 Actions 注释为账户 billing lock;本地与部署验收命令见维护质量。

Telegram + 飞书 ↔ tmux 内 AI CLI(Claude Code / Codex / Oh My Pi)双向桥 —— 远程在 IM 话题发消息推动精确 tmux pane 里的 CLI,输出实时回推同一话题。

不调 API、不走 headless claude -p / SDK 路径、用 tmux pane TUI 注入 —— 保留本地交互式 CLI 作为唯一执行面。


为什么需要 tmuxbot?(2026-06-15 背景)

Anthropic 文档说明:从 2026-06-15 起,Claude 订阅用户的 Agent SDK / claude -p / Claude Code GitHub Actions / 第三方 Agent SDK app 会走独立的 Agent SDK monthly credit;交互式 Claude Code terminal / IDE 继续走原订阅 usage limits。

明确走 Agent SDK credit 文档说明仍走交互式订阅 usage limits
Claude Agent SDK 交互式 Claude Code terminal / IDE
claude -p headless / --print mode 在 IDE 插件里用 Claude Code
Claude Code GitHub Actions Claude web / desktop / mobile conversations
基于 Agent SDK 的第三方应用 —

很多 IM ↔ Claude bridge 采用 Agent SDK 或 claude -p headless 子进程路线,这类路径已经被官方明确归入 Agent SDK credit。tmuxbot 的设计目标是避开这些 headless/programmatic 执行面,只远程控制本机已经存在的交互式 TUI。

tmuxbot 用 tmux pane TUI 注入:

  • bot 通过 tmux paste-buffer 把消息粘到 pane 里
  • pane 里的 claude / codex 是正常 TUI 模式跑,不是 -p / SDK
  • jsonl 写到 ~/.claude/projects/<encoded-cwd>/*.jsonl,跟人手动跑完全一样

这不是官方政策承诺,而是项目的工程边界:不调用 vendor API、不派 headless 子进程、不把 IM bridge 做成 Agent SDK app。是否以及如何计量最终以各 CLI/vendor 的实际规则为准。

这是 tmuxbot 区别于 SDK/headless bridge 的核心价值。


这是什么?

一个 Python(3.10+)的 IM ↔ AI CLI 双向桥,可插拔架构:

  • 前端(IM):Telegram、飞书(lark-oapi WebSocket 长连接)
  • 后端(AI CLI):Claude Code、OpenAI Codex CLI、Oh My Pi(OMP)
  • 架构原则:一个 IM credential 管多个精确 topic route;每个 route 绑定一个 tmux pane 并选择自己的 adapter

真正实用的场景

  • 不在电脑前时,用手机 TG 或飞书推动本地 AI 跑代码 / 改项目 / 看日志
  • 多项目并行:每个项目一个 tmux session 一个 cwd,各自加载项目自己的 CLAUDE.md
  • 多 CLI 共存:同一个项目群的不同话题可分别接 Claude、Codex、OMP,SSH attach 的仍是同一批真实 pane

30 秒上手

要求:Linux、Python 3.10+、tmux,以及至少一个已安装的交互式 CLI(Claude Code / Codex / Oh My Pi)。

uv tool install 'tmuxbot[full]'
tmuxbot doctor
tmuxbot serve --open

首次运行会自动打开中文 WebUI,并生成 10 分钟有效、设置成功后立即失效的一次性本机授权。没有 .env、通道或 binding 时 WebUI 也会保持可用;bridge 显示“尚未配置”。运行 tmuxbot doctor 可检查 tmux、Claude Code、Codex、Oh My Pi 和运行目录。

配置入口:

为避免弱模型手工拼错 YAML、thread ID、tmux 或 systemd,Admin DM 使用独立 workspace(默认 ~/.local/share/tmuxbot/admin),避免根目录管理规则污染普通项目会话。安装命令会生成统一的 Admin Operations Contract、部署 runbook 和可校验 manifest:

tmuxbot admin --file /path/to/bindings.yaml --service tmuxbot.service \
  install-contract
tmuxbot admin --file /path/to/bindings.yaml --service tmuxbot.service \
  verify-context --json
tmuxbot admin --file /path/to/bindings.yaml --service tmuxbot.service \
  provision-project --name demo-omp --channel telegram \
  --credential TG_OMP_BOT_TOKEN \
  --topic-link https://t.me/c/CHAT/THREAD \
  --cwd /absolute/project/demo --backend omp
# 新话题则改用 --chat-id + --topic-title;核对 plan 后原命令增加 --apply。
# inventory / telegram-topic / feishu-topics / create-topic / bind-topic / verify
# 保留为低层诊断、恢复和迁移接口。

事务内部负责完整候选校验、原子 YAML 替换、监督服务重启、post-apply verify 和失败回滚;LLM 只负责提供明确的 endpoint、target、cwd 与 adapter。

生产部署(systemd,推荐)

推荐先用 Claude Code native installer 安装 claude,并在 .env 里写绝对路径:

curl -fsSL https://claude.ai/install.sh | bash
echo "CLAUDE_BIN=$HOME/.local/bin/claude" >> .env

CLAUDE_BIN 会在拉起 Claude 时读取,避免 systemd/tmux 的非交互 shell PATH 找不到 claude,也避免命中坏掉的 npm 全局安装。CODEX_BIN 与 OMP_BIN 同理可指向绝对路径;OMP route 使用 backend: omp,新建 Telegram 通道默认 credential env 为 TG_OMP_BOT_TOKEN。

Codex 的模型不由 tmuxbot 写死。每次新建或恢复 Codex TUI 时,tmuxbot 都读取 ~/.codex/config.toml 顶层 model,存在时传递 -m <model>;因此只要修改 Codex 自身配置,之后的新会话和恢复会话都会自动使用新默认模型。配置缺失或无效时会省略 -m,交由 Codex 原生默认行为处理。

Runtime V2 仍然直接操作 tmux 内的交互式 CLI。建议先配置 TMUXBOT_RUNTIME_V2=shadow:线上继续发送兼容路径结果,同时只比较脱敏后的事件结构; 日志无 mismatch 后再切 on。TMUXBOT_CLAUDE_HOOKS=true 会幂等安装 tmuxbot 自有 Claude hooks,用于会话身份与 Stop 最终回复;hooks 只写本地 spool,不会直接发 IM, JSONL 和终端状态探测仍继续工作。

mkdir -p ~/.config/systemd/user
ln -sf "$(pwd)/deploy/systemd/tmuxbot.service" ~/.config/systemd/user/tmuxbot.service
systemctl --user daemon-reload
systemctl --user enable --now tmuxbot.service
loginctl enable-linger $USER

# 或由安装器生成同一个 unit;健康审计始终非破坏且只检查已有 pane
# tmuxbot install-service --now

# 看日志 / 重启 / 停
journalctl --user -u tmuxbot -f
systemctl --user restart tmuxbot
systemctl --user stop tmuxbot

生产主机只应启用一个 tmuxbot.service。同一进程可承载多个 Telegram Bot 和飞书 App credential;每个飞书 App 使用隔离的 SDK event loop,避免 lark-oapi 的模块级 loop 在多 App 间互相覆盖。旧版 tmuxbot-bridge-refresh@*.timer 不再需要:安装器会 停用并删除该周期强制重启 helper,连接恢复由 frontend 自身重连循环负责。

Restart=always 会在主进程或 bridge child 异常退出后 5 秒内自动拉起;unit 关闭 systemd start-limit,瞬时连续故障不会让服务永久停在 failed。运行中可在 WebUI 的 /api/channel-health 查看只读连接审计(连接时间、最近收包、最近有效入站、恢复次数)。

tmux 会话默认按消息懒启动:手动执行 tmux kill-session -t <name>,或在 Telegram/飞书发送 /tmuxstop 后,后台不会周期性复活它;下一条消息到达时会自动重建 tmux,并恢复已绑定的 Claude/Codex/OMP provider 会话。安装器默认设置 TMUXBOT_LIFECYCLE_ENABLED=1,用于非破坏性健康审计。watchdog 默认每 60 分钟仅巡检 已存在的 route pane:验证 provider 前台进程与健康状态,必要时仅恢复该 route 的异常 provider 进程树。它不会按空闲时间退出 Claude/Codex/OMP,不会重建被人工关闭的 tmux,也不会执行 tmux kill-server;缺失 target 仍等下一条精确 route 消息按需恢复。Telegram、飞书和 Web 控制面板都提供带确认的“关闭 tmux”操作,管理记录和历史不会被删除。旧多服务主机的合并、offset 防回吐、 回滚和验收步骤见 docs/single-service-operations.md。

Web control plane

推荐统一入口会启动 Web,并按配置状态监督独立 bridge child:

tmuxbot serve --open

默认监听 127.0.0.1:8765。tmuxbot web 仍可只启动 Web;tmuxbot bridge 仍保留严格配置检查。配置、数据和状态默认使用 XDG 目录:~/.config/tmuxbot、~/.local/share/tmuxbot、~/.local/state/tmuxbot。

需要常驻时:

tmuxbot install-service --now
journalctl --user -u tmuxbot -f

不要把 Web 端口直接暴露到公网。 远程访问应通过带 TLS 和访问控制的反向代理, 并设置 TMUXBOT_WEB_SECURE_COOKIE=true 与准确的 TMUXBOT_WEB_PUBLIC_ORIGIN。 deploy/systemd/tmuxbot-web.service 提供独立 unit 示例;其中凭证只从 .env 读取, 不会出现在 ExecStart 命令行。


当前能力

  • 零配置中文 WebUI:uv tool install 'tmuxbot[full]' 后运行 tmuxbot serve --open;可验证项目目录、显示 Git 与已有 pane、扫描/探测 tmux、Claude Code、Codex、Oh My Pi,登记项目并启动受管 CLI。已有 pane 可先以只读模式直接查看,手动接管后才允许输入;模型候选仍由当前 CLI 的原生 /model picker 提供。
  • 原生 Web TUI:xterm.js 直接 attach 已登记 tmux target,默认只观察;显式接管后才允许键盘输入,断开浏览器不会终止 tmux 会话
  • Web 通道向导:可为受管会话配置 Telegram 或飞书,密钥只写入本机 0600 配置,不通过 API 回显;浏览器只提交 provider ID,binary、tmux target 和启动参数均由服务端 registry 管理
  • TeamRun 多 LLM:确定性 Coordinator / Implementer / Reviewer 三角色协作,唯一写租约、DAG、mailbox、Artifact、重试、独立验收和恢复;Implementer 交付证据后 Reviewer 自动收到只读审查包
  • 双前端:Telegram(DM / 普通群 / supergroup forum topic)+ 飞书(群聊 / 私聊,Card JSON 2.0 收发/编辑;操作统一使用 / 命令)
  • 中文控制面板:/menu 主动打开轻量面板(/panel、/settings 兼容保留),可切换群聊 @ 策略、执行 /status /screen /new /compact /resume /esc /cc。模型候选由当前 tmux CLI 的原生 /model 选择器实时提供,面板会显示已读取的当前模型。受管 Codex 会话在新建与重启恢复时读取 ~/.codex/config.toml 的 model;可在当前会话中用原生 /model 临时切换,下一次 bot 重启则应用最新配置。面板也提供带二次确认的“重启 CLI”,Codex/Claude 都会恢复原 provider 会话与 transcript,保留上下文;Claude 模型卡额外提供“仅本会话”,避免修改未来新会话默认模型
  • @ 策略命令:/mention on 表示无需 @,/mention off 表示必须 @,/mention default 恢复部署默认,/mention status 查看当前策略;设置按 binding 持久化且立即生效
  • 按 route 选择 adapter:同一 Telegram Bot/飞书 App credential 可按精确 topic/thread route 混合承载 Claude Code、Codex 和 OMP;不同 credential 仍可并行部署
  • 核心命令:/status /info /whoami /new /resume /rename /esc /cc /eof /screen /restart /tmuxstop。OMP route 的 /exit 先透传给受管 OMP;随后立即清除旧 transcript pin,并在 3 秒后 clean respawn 一个不带 --resume 的全新 OMP 会话。新进程会重新读取 OMP 启动配置和已安装插件,完成后在 IM 回报;它不保留上一个会话上下文。/restart 仍是保留精确 provider 会话与 transcript 的受管重启。对 OMP,bot /plan 是本地帮助:只报告当前 plan 状态,并提示 SSH attach 后使用默认 Alt+Shift+P(自定义 keybinding 可能不同),不会向 pane 注入 /plan
  • TUI 透传:/context /cost /usage /compact /clear 等,抓屏结构化反馈
  • 工具调用聚合:一个 turn 内的 tool_use 流式刷同一条 IM 消息,真说话单独 push 触发通知;OMP 成功执行 edit 时同步显示受限 diff,成功执行普通本地 write 时同步显示受限代码片段,内部工具 URI 和敏感文件内容不外发
  • Codex 计划跟随:update_plan 会维护一条可编辑的“当前计划”消息,TG/飞书里持续显示最新 in_progress / pending / completed 状态
  • 双向附件:Telegram/飞书收到的图片/文件会下载到本机并以 @path 注入 TUI;AI 回复里的绝对/相对路径、Markdown 文件链接和图片链接会转成原生 IM 附件,聊天内容不暴露服务器绝对路径
  • 统一富消息:Claude/Codex/OMP 共用 ReplyDocument;回复详细信息会显示运行时模型与档位(如 gpt-5.6-terra medium);代码围栏可保留语言与 filename=... 标签,Markdown 表格在 Telegram 退化为对齐的原生 <pre> 数据块,在飞书使用 Card 2.0 根级 table 组件;Telegram 继续使用安全 HTML/可展开引用,飞书使用 header、summary、状态色和可选 CardKit 流式更新
  • 长回复自动分页:Telegram 按 HTML/UTF-16 安全边界拆成多条消息并保持代码块标签完整;飞书同时按 Card JSON 2.0 的 30KB payload 和每卡最多 50 个 body element 拆成连续卡片,不再因大量短 Markdown 段落触发 element exceeds the limit,也不把普通长回复截断成预览或强制改发 TXT
  • Telegram 状态标识:Telegram 没有飞书式原生彩色卡片标题,使用 🟡 工作中、🟠 等待输入、✅ 已完成、🔴 错误/阻塞、🔵 信息、⚪ 状态未知 作为文本等价呈现
  • 飞书状态色:工作中黄色、等待输入橙色、完成/空闲绿色、错误/阻塞红色、普通信息蓝色、未知状态灰色;流式回复从黄色开始并在成功完成后变为绿色
  • OMP 精确身份:受管 extension 写入 target-scoped handoff 与 health sidecar;handoff 记录 tmuxTarget/cwd/sessionId/transcriptPath/processId,health 记录同一会话身份与状态。新会话 JSONL 首条消息前可能尚未落盘,此时只接受官方 ~/.omp/agent/sessions 路径、匹配 session ID 且 processId 属于该 pane 的 provider-authored record;文件出现后立即回到 header/cwd 校验。恢复只使用 omp --resume <absolute transcript path>,不按 mtime 或 cwd 猜测会话
  • OMP 原生运行语义:普通文字和附件在 working/streaming 时进入 steering queue;/new、/compact 等控制命令要求 idle,忙碌时立即拒绝。状态以 provider-authored sidecar 和 JSONL v3 为权威;IM 状态栏优先显示当前上下文已用/上限/余量、会话累计 token、最近一轮缓存命中率、自动压缩、模型与思考强度,用于判断继续、压缩或新建会话。会话文件 MB 不作为 token 指标;原生 footer 仅是版本化弱信号。
  • OMP 交互安全:原生菜单、picker、ask、approval、plan review 和确认只通知精确 pane 的 SSH attach 命令;Telegram/飞书不模拟方向键、Enter、批准或取消按键
  • 活性指示:provider-authored health、JSONL 进展与严格的当前 live loader 共同判定状态;工作中显示 typing(Telegram),飞书无 typing API
  • 消息已读反应:TG 👀 emoji(Bot API 7.0+);飞书 👀 OnIt reaction
  • 订阅配额:/status 展示 5h/7d 五窗口 utilization + 精确重置倒计时(走 OAuth API)
  • 健壮性:tmux paste 等 TUI idle 后提交,并读取 Claude/Codex/OMP 活动输入框确认;OMP steering 是唯一 busy 普通消息例外,控制命令仍 fail fast。OMP 17.3.3 附件 @path 打开文件补全时,首个 Enter 只接受补全也不会把消息留在输入框,tmuxbot 会确认草稿仍在并有限重试提交。Telegram 最终回复逐分片校验 Bot API message_id,未确认送达时不推进 JSONL offset、下轮自动重试;tailer 另有 512KB 积压保护、GC 强引用和 offsets debounce。源码部署的 bin/restart.sh 会先重装当前 checkout 的 uv tool,避免 systemd 运行旧 wheel

架构

TG 用户                飞书用户
  │                       │
  ├─ @claude_bot ─┐   ┌─ 飞书 App ─┐
  │               │   │            │
  ▼               ▼   ▼            ▼
TelegramFrontend      FeishuFrontend
(aiogram polling)     (lark-oapi WebSocket)
  │                       │
  └───────────────────────┘
              │
        dispatch.py (共享命令分发层)
              │
     ┌────────┼────────┐
     │        │        │
ClaudeCode  Codex      OMP
 Backend    Backend   Backend
     │        │        │
     └────────┼────────┘
              │
         tmux pane(s)
     TUI idle 轮询 → paste-buffer
     → composer 渲染 → Enter → 确认/有限重试
              │
         jsonl tailer
     parse_event + aggregator
              │
        推回 IM 前端

技术细节看 DEVELOPMENT.md。

富消息与附件配置

飞书默认启用 Card JSON 2.0。需要临时回滚旧卡片时设置 TMUXBOT_FEISHU_CARD_V2=0。CardKit 流式更新默认关闭;确认应用已订阅 card.action.trigger 并拥有 cardkit:card:write 权限后,可设置 TMUXBOT_FEISHU_STREAMING=1 灰度启用。多飞书应用可以使用 FEISHU_CARD_V2、FEISHU_STREAMING 等按 bot_token_env 前缀覆盖。

回复里的本地文件只有在以下目录内才会自动上传:binding 的 cwd、 TMUXBOT_ATTACHMENT_DIR、操作系统临时目录,以及 TMUXBOT_ATTACHMENT_ALLOWED_ROOTS 明确配置的目录。额外目录在 Linux 上使用 冒号分隔。目录、设备、socket、不存在的文件和安全根之外的路径不会上传; 上传失败只向聊天显示安全文件名,不显示服务器绝对路径。

维护质量

make install-dev
make check
make check-web   # 会先按 package-lock 执行 npm ci
# 发布机额外运行(会检查本机 tmux/CLI/运行目录)
make release-check

v0.3.0 是冻结的产品化基线;当前 main / v0.3.1 完成 OMP clean cutover。发布点使用 vMAJOR.MINOR.PATCH 标签保存。产品边界、冻结能力和下一阶段维护债务见 PRODUCTIZATION.md。

持续迭代入口:


路线图

  • M1 ✅ 单文件骨架 + 双 binding + 命令组 + heartbeat
  • M2 ✅ 代码审查 + 可插拔重构(backends/ + frontends/ + dispatch.py)
  • M3 ✅ 接入 Codex CLI + 多 bot 共存 + systemd 部署
  • M4 ✅ 接入飞书前端(lark-oapi WebSocket + interactive card)+ 多实例支持
  • 0.3.0 ✅ Runtime V2、中文 WebUI、XDG/doctor/systemd 安装面、终端接管与 TeamRun 基线
  • 0.3.1 ✅ Oh My Pi 原生适配:OMP v3、受管身份 sidecar、精确恢复、SSH-only 原生交互与 Web/doctor/config clean cutover

License

MIT

About

Telegram/飞书 ↔ tmux AI CLI 双向桥:精确 topic/thread 路由到 Claude Code、Codex、Pi 交互 TUI,支持 WebUI、附件与 systemd

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages