AI coding agent 最麻烦的时刻，往往不是它开始写代码，而是你已经让它跑起来了，人却要离开电脑。构建还没结束，测试可能会问权限，agent 可能卡在一个需要确认的 prompt。把整段任务丢给远程服务是一种解法，但很多人的实际工作流仍然在本机终端里：tmux session、项目目录、未提交 diff、shell 环境和已经打开的 agent CLI。

今天看的是 alexei-led/ccgram。它的定位很窄：做一个 Telegram 和终端复用器之间的桥，让你在手机上看 Claude Code、Codex、Gemini、Pi 或普通 shell 的输出，并把回复送回同一个终端会话。它不包装某个 agent SDK，也不替你创建一个新的云端对话。README 里最关键的设计点是：agent 进程仍然留在 tmux、herdr 或 agterm 里，终端会话是事实来源，Telegram 只是远程控制面。

按 GitHub repository API、README、pyproject.toml、latest release、tags 和 commits API 在 2026-08-31 18:05 Asia/Shanghai 能核验的信息，alexei-led/ccgram 当前有 258 stars、75 forks。主要语言是 Python，许可证是 MIT，默认分支是 main，仓库创建于 2026-02-10 09:35:58 UTC，latest push 是 2026-08-31 09:42:49 UTC。最新提交是 d8d1ef7，提交时间 2026-08-31 09:42:48 UTC，主题是隔离 multiplexer status test 的环境。最新 GitHub Release 是 v4.9.3，发布时间 2026-08-31 09:40:08 UTC；pyproject.toml 里包名是 ccgram，要求 Python 3.14+。

项目概览

属性详情
仓库alexei-led/ccgram
定位Telegram 到 tmux / herdr / agterm 的终端 agent 控制桥
Stars258
Forks75
主要语言Python
许可证MIT
创建时间2026-02-10 09:35:58 UTC
Latest push2026-08-31 09:42:49 UTC
最近提交d8d1ef7，2026-08-31 09:42:48 UTC
最新 Releasev4.9.3，2026-08-31 09:40:08 UTC
运行要求Python 3.14+；tmux、herdr 或 agterm；一个 agent CLI
关键词Telegram bot、tmux、herdr、agterm、Codex、Claude Code、Gemini CLI

它解决的是离开终端后的接管问题

很多 Telegram bot 会把 agent API 包进聊天窗口，这种方式适合从零开始的远程对话，但不适合接管已经在本机跑着的任务。你回到桌面时，希望还能 attach 回原来的 tmux window，看到完整 scrollback，继续用本机编辑器、git 和 shell。CCGram 选择的边界正好相反：它不把 agent 从终端里搬走，而是在终端复用器上方加一层消息通道。

这个设计的好处是 workflow 不会断。桌面端启动的 Codex 或 Claude Code 仍然在原来的项目目录里，环境变量、worktree、权限提示和文件系统状态都按本机规则走。你离开电脑后，Telegram 可以继续收到输出，必要时发送命令、斜杠指令、Enter、Esc 或语音消息。回到电脑后，再 attach 到同一个 session，不需要把一段云端聊天手动同步回本地。

README 里的 topic 映射也很实际。Telegram group 的 forum topic 可以对应一个 tmux window、一个 guarded Herdr agent session，或一个 durable agterm session UUID。这样同时跑多个 agent 时，api、ui、data、ops 可以分别是不同 topic，而不是混在同一个聊天流里。对经常并行开几个 agent 的人来说，这比“手机上看一条长日志”更接近真实工作台。

重点不是聊天，而是会话安全和可恢复

CCGram 的 README 花了不少篇幅讲 delivery、sync 和 session binding，这比单纯展示 bot 命令更有价值。长时间跑 agent 时，消息重复、积压、重启恢复和 topic 清理都不是边缘问题。工具如果在这些地方随便处理，远程控制很快就会变成新的不确定性来源。

它的做法是保留 raw provider transcript，不在 Telegram 发送失败时静默丢消息；delivery 是 at-least-once，所以重启或失败可能重复一段 transcript，但不会假装已经成功。严重 backlog 时，状态消息会给出跳到 live 的确认动作，并留下 skipped-range notice。/sync 只清理本地记录里符合条件的 retired topics，不会枚举和删除任意 Telegram topic。

Herdr 绑定部分也能看出项目关注的是操作边界。CCGram 不把 tab、pane 或名字当成永久身份，而是读取 agent.list 里的 session identity；缺失、格式异常、legacy binding 或重复 canonical target 会 fail closed 或 quarantine。这些细节听起来繁琐，但远程给 agent 发送输入时，最重要的就是不要把命令送到错误的 pane。

安装路径清楚，但前置条件不轻

README 推荐的安装方式是：

uv tool install ccgram
# 或者 pipx install ccgram / brew install alexei-led/tap/ccgram

然后需要在 Telegram 里通过 BotFather 创建 bot，把 bot 加入启用 Topics 的群组并提升为 Admin，再在 ~/.ccgram/.env 里配置 TELEGRAM_BOT_TOKEN、ALLOWED_USERS 和 CCGRAM_GROUP_ID。启动 ccgram 后，在 Telegram topic 里发消息，目录浏览器会让你选择项目目录和要启动或绑定的 provider。

这不是“安装一个 app 就好”的工具。你需要理解 Telegram bot 权限、群组 topic、tmux/herdr/agterm，以及本机 agent CLI 的运行方式。好消息是它没有假装这些复杂性不存在，而是把它们作为明确配置暴露出来。对个人 power user 或小团队，这种透明度比过度自动化更可靠。

平台支持也要看清楚：Linux、macOS 和 WSL2 可以用，native Windows 不支持。原因也合理，CCGram 依赖 Unix file locking、signal handling 和 terminal multiplexer 能力。agterm backend 是 macOS-native；Windows 用户需要在 WSL2 里跑 tmux 或 herdr。

和 herdr 不是同一层

Gumi 之前写过 herdr，那是 AI agent 专用 terminal workspace manager。CCGram 可以接 herdr，但它不试图替代 herdr。更准确的关系是：herdr 管 session 和 workspace，CCGram 管远程消息入口。tmux 和 agterm 也是同理。CCGram 的价值不在于设计一个新终端，而在于承认很多人已经有终端复用器，然后把手机接到那个现有运行环境上。

这也解释了为什么它比普通通知脚本更有意思。通知只能告诉你“有输出了”或“任务结束了”，CCGram 让你在同一个 topic 里看 live view、发输入、恢复 session、发送工作区文件，甚至用 provider-specific toolbar 做 Screenshot、Mode、Esc、Enter 这类动作。它把远程控制做成双向，而不是只做提醒。

适合谁

第一类是经常让 agent 跑长任务的人。比如让 Codex 改一个中等规模 feature、让 Claude Code 清理测试、让 Gemini CLI 扫文档。你不想一直坐在电脑前等，但又不想把整个开发环境迁到云端。

第二类是喜欢 tmux 或 herdr 的本地派用户。你的 session、scrollback、shell history、git 状态都在本机，Telegram 只是临时接管入口。这个边界适合对源码、凭据和本机环境比较敏感的工作流。

第三类是同时管理多个 agent session 的人。Telegram forum topics 和 tmux window / herdr session / agterm UUID 的映射，让并行任务更容易分隔，也减少把回复发错地方的风险。

Caveats

第一，运行要求偏新。pyproject.toml 写明需要 Python 3.14+，这在很多系统上还不是默认版本。安装前最好先确认 uv、pipx 或 Homebrew 的 Python 路径。

第二，Telegram 本身会变成协作边界的一部分。bot token、group admin 权限、allowed user ID、topic 权限都要认真配置。把 agent shell 输入接到聊天软件上，本质上就是把一部分操作能力交给 bot。

第三，它依赖终端复用器的语义。tmux、herdr、agterm 的 session identity、pane 状态和后台进程如果已经混乱，CCGram 只能在上层做防护，不能替你整理底层工作台。第一次使用时，最好从一个低风险项目和一个独立 topic 开始。

总结

alexei-led/ccgram 有意思的地方，是它没有把 AI coding agent 远程控制做成新的封闭平台。它站在现有终端 session 上，让 Telegram 成为观察、回复和恢复的通道。对仍然把本机终端当作开发事实来源的人来说，这个方向很实用。

它不是给所有人的轻量玩具。Python 3.14+、Telegram bot 权限、tmux/herdr/agterm、agent CLI 都需要你理解。但如果你的真实痛点是“agent 在跑，我人必须离开电脑”，CCGram 正好补的是这块空白。

项目地址：https://github.com/alexei-led/ccgram