CCGram：基于tmux与Telegram的远程AI编程助手控制方案

1. 项目概述用手机遥控你的AI编程助手作为一名常年和终端、AI编程工具打交道的开发者我经常遇到一个尴尬的场景在本地终端启动了一个Claude Code或者Codex CLI会话正和AI助手热火朝天地讨论代码重构方案突然需要离开电脑——可能是去开个会或者只是想在沙发上换个姿势。这时候会话虽然还在后台运行但我完全失去了对它的掌控。等我回来要么错过了AI的关键提问要么得花时间重新梳理上下文。CCGram这个项目完美地解决了这个痛点。它的核心思路非常巧妙不直接与AI助手的SDK交互而是作为你本地tmux会话的“遥控器”。简单来说它把你的Telegram群组变成了一个远程终端监控与控制面板。每个Telegram的“论坛话题”对应一个tmux窗口你在手机上发送的消息会被转换成按键指令发送给对应的tmux窗格而tmux窗格里的输出包括AI的回复、交互式提示则会被实时抓取并推送到你的Telegram。这意味着你的AI编程会话始终运行在你自己的机器上数据不出本地安全可控。你可以随时用tmux attach无缝切回桌面端继续操作也可以在任何有网络的地方通过手机监控进度、回复提示、甚至发送文件。对于需要长时间运行代码生成、测试或调试的任务来说这种“不离线”的连续性体验提升是巨大的。2. 核心设计思路与架构解析CCGram的设计哲学是“轻量桥接而非重写封装”。市面上有些Telegram机器人会把AI助手的SDK整个包一层做成一个独立的API服务。这样做的问题在于你被锁死在了那个机器人的环境里一旦离开会话历史和上下文就断了也无法利用你本地已经配置好的开发环境。2.1 基于tmux的透明桥接CCGram选择了另一条路它承认tmux才是终端会话管理的“事实标准”。因此它的角色不是一个替代品而是一个增强插件。其架构可以分解为三个核心部分Telegram前端一个运行在你服务器或本地电脑上的Bot。它监听指定群组中各个话题Topic的消息。每个话题被视为一个独立的“远程会话”。tmux后端在你的开发机上一个或多个tmux会话中运行着真正的AI助手如claudecodex或Shell。CCGram通过Python的libtmux库与这些tmux窗格进行交互。CCGram桥接层这是核心逻辑所在。它执行两个主要循环读取循环定期或基于事件检查绑定的tmux窗格的输出内容。它不仅仅抓取原始文本还会解析其中结构化的信息比如Claude Code的“询问用户”交互块、工具执行结果、状态变更等。写入循环监听Telegram消息将文本消息或处理后的语音转文本通过tmux send-keys命令原样“键入”到对应的tmux窗格中。这种设计带来了几个关键优势零数据迁移所有会话状态、历史记录、项目文件都在你本地的tmux里CCGram只是提供了一个观察和输入的“窗口”。无损恢复即使CCGram进程崩溃重启只要tmux会话还在重新启动CCGram就能重新绑定并恢复控制消息断点续传。环境原生AI助手运行在你本地的开发环境中可以无障碍地访问你的git仓库、包管理器、测试套件、环境变量等一切资源。2.2 多会话与多提供者支持一个强大的特性是它对并行工作流的支持。你可以在一个Telegram群组里创建多个话题例如#api-refactor- 绑定到tmux窗口0运行claude重构后端API。#ui-component- 绑定到tmux窗口1运行codex编写React组件。#data-pipeline- 绑定到tmux窗口2运行gemini优化数据脚本。#ops-deploy- 绑定到tmux窗口3运行shell提供者通过自然语言执行部署命令。CCGram会自动检测每个tmux窗口中运行的进程来识别其“提供者”Provider。识别逻辑是分层的进程名匹配快速路径直接检查tmux list-panes输出中的进程名匹配claudecodex等。TTY回溯查询JS运行时回退有些工具如通过node或bun运行的包装脚本进程名不是直接的提供者。此时CCGram会执行ps -t tty命令查找该终端下运行的进程树来推断真正的提供者。窗格标题符号Gemini回退作为最后的手段会解析tmux窗格标题中预定义的符号如♊来识别。这种多提供者共存的模式让你可以同时驾驭多个不同的AI助手针对不同任务选用最合适的工具并通过统一的Telegram界面进行管理。3. 详细配置与实操部署指南要让CCGram跑起来需要完成几个关键步骤的配置。下面我以在Ubuntu服务器上部署为例分享从零开始的详细过程。3.1 环境准备与依赖安装首先确保你的基础环境就绪# 1. 确保Python版本符合要求 (3.14) python3 --version # 如果版本较低考虑使用pyenv或conda管理多版本Python # 2. 安装tmux如果尚未安装 sudo apt update sudo apt install -y tmux # 3. 安装至少一个AI助手CLI # 例如安装Claude Code假设你已有Anthropic API Key pip install claude-code # 首次运行需要配置API Key claude auth注意claude-code的认证信息通常存储在~/.config/claude/config.json。确保CCGram运行时尤其是以服务运行时的用户有权限读取此文件。3.2 创建与配置Telegram Bot这是连接手机与电脑的关键一步每一步都不能错创建Bot在Telegram中搜索并联系BotFather。发送/newbot指令按提示操作。Bot名称可以随意如MyDevAssistantBot。Bot用户名必须以bot结尾如my_dev_assistant_bot。创建成功后BotFather会给你一个HTTP API Token形如1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ。妥善保存它只会显示一次。关键Bot设置继续与BotFather对话对你的Bot进行如下设置/setprivacy - 选择你的Bot设置为 Disable (关闭隐私模式)。这**至关重要**否则Bot在群组里看不到用户消息。 /setjoingroups - 设置为 Enable允许Bot被加入群组。 /setforum - 设置为 Enable允许Bot在论坛话题中工作。创建群组并添加Bot在Telegram创建一个新的群组Group。在群组设置中开启“论坛”功能。这会将该群组转换为一个论坛可以创建话题。将你刚刚创建的Bot添加到这个群组。提升Bot为管理员在群组成员列表中找到Bot将其权限设置为管理员。必须勾选以下权限Post Messages(发布消息)Edit Messages(编辑消息)Pin Messages(置顶消息)Manage Topics(管理话题) -这个非常重要其他权限如删除消息等可根据需要选择非必需。3.3 获取必要的ID信息CCGram需要两个ID来精确控制通信范围你的Telegram用户ID在Telegram中搜索userinfobot打开并发送任意消息如/start。它会回复你的用户ID是一个纯数字如987654321。记录下这个数字。群组ID将RawDataBot添加到你的论坛群组。在群组里RawDataBot 会自动发送一条包含该聊天详细信息的消息。在消息中找到id字段。如果它是一个正数如123456789你需要在其前面加上-100前缀得到-100123456789。如果它已经是一个很大的负数直接使用即可。获取ID后可以将 RawDataBot 移出群组。3.4 安装与配置CCGram推荐使用uv进行安装它能更好地处理依赖隔离# 安装uv如果尚未安装 curl -LsSf https://astral.sh/uv/install.sh | sh # 重新加载shell配置 source ~/.bashrc # 使用uv安装ccgram uv tool install ccgram接下来创建配置文件# 创建CCGram的配置目录 mkdir -p ~/.ccgram # 创建环境变量配置文件 nano ~/.ccgram/.env在.env文件中填入以下内容替换为你自己的信息# 必须从BotFather获取的Token TELEGRAM_BOT_TOKEN1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ # 必须允许控制Bot的用户ID多个用逗号分隔 ALLOWED_USERS987654321 # 可选限制Bot只在该群组工作避免干扰其他群。值为前面获取的群组ID。 CCGRAM_GROUP_ID-100123456789 # 可选设置默认的AI提供者如果创建会话时不指定则使用此值 CCGRAM_PROVIDERclaude # 可选如果你想使用Shell提供者的LLM命令生成功能或启用完成摘要需要配置 # CCGRAM_LLM_PROVIDERopenai # CCGRAM_LLM_API_KEYsk-... # 可选启用语音消息转录需要OpenAI或Groq的Whisper API # CCGRAM_WHISPER_PROVIDERopenai # OPENAI_API_KEYsk-... # 如果LLM和Whisper都用OpenAI可以只设这个3.5 安装Claude Code钩子强烈推荐如果你主要使用Claude Code安装其钩子能获得最佳体验ccgram hook --install这个命令会向Claude Code注册一系列钩子hook使得CCGram能即时检测交互式UIClaude弹出“询问用户”或“请求权限”对话框时CCGram能立刻知道并在Telegram中渲染成内联键盘而不是等终端输出刷新。捕获API错误网络错误或API限额问题能立即通知到你。跟踪子代理/团队在使用Claude的团队模式时能更好地管理多个并发任务。实操心得即使不安装钩子CCGram也能通过终端抓取scraping工作但响应速度和可靠性会差一些。安装钩子后体验是“即时”的强烈建议所有Claude Code用户都执行这一步。如果启动CCGram时提示钩子未安装它会给出修复命令。3.6 运行与测试现在可以启动CCGram了ccgram如果一切配置正确你会在终端看到启动日志Bot显示为在线。现在回到你的Telegram论坛群组点击底部的“创建话题”按钮新建一个话题可以命名为“Test-Claude”。在该话题中向Bot发送任意消息例如“hello”。此时Bot会回复一个交互式的目录浏览器。这是让你选择这个AI会话在哪个项目目录下工作。导航并选择你的一个项目目录例如~/projects/my-api。选择AI提供者例如Claude。选择会话模式✅ Standard标准模式或 YOLO激进模式后者可能跳过一些确认步骤。完成选择后CCGram会在后台创建一个tmux窗口启动Claude Code并将该话题与这个tmux窗口绑定。之后你在这个话题里发送的所有文本都会直接“输入”到Claude的对话中。4. 核心功能深度体验与技巧CCGram的功能相当丰富远不止简单的消息转发。下面我挑几个最能提升效率的功能详细说说。4.1 交互式提示与内联键盘当AI助手尤其是Claude Code需要用户输入时比如询问“是否执行这个计划”或“请提供更多细节”传统的终端会阻塞等待。在CCGram里这些提示会被解析成Telegram的内联键盘。例如Claude问“AskUserQuestion: Should I proceed with refactoring theauthmodule? (yes/no)”。在Telegram话题里你会看到这条消息下面附带了[ Yes ]和[ No ]两个按钮。你不需要打字直接点击按钮对应的选择y或n就会被发送给Claude。注意事项确保你的Bot有Inline Queries相关权限通常在BotFather创建时默认有。如果点击按钮没反应检查Bot的隐私模式是否已关闭/setprivacytoDisable。4.2 语音消息与命令转录这是一个“真香”功能。当你在通勤路上不方便打字时可以直接按住Telegram的麦克风按钮发送语音。CCGram支持配置Whisper APIOpenAI或Groq将语音转成文字。更妙的是处理流程转写完成后消息不会直接发送。Bot会先显示转写文本并附带Send和Discard按钮。你可以检查转写是否准确确认无误后再点击Send转发给AI避免因语音识别错误导致AI误解。对于Shell提供者语音消息会先经过LLM被理解成一条可能的Shell命令再次经你确认后执行。例如你说“列出当前目录下所有的Python文件并计算行数”LLM可能会生成命令find . -name *.py -exec wc -l {} | tail -1经你确认后执行。4.3 文件传输 (/send命令)调试时经常需要查看生成的文件或日志。CCGram的/send命令让你能直接从工作区发送文件到Telegram。/send README.md发送指定路径的文件。/send *.png使用通配符发送所有PNG图片。/send error在当前项目目录下递归搜索文件名包含“error”的文件并以交互列表呈现。直接发送/send启动一个交互式文件浏览器可以逐级导航目录。安全机制这个功能设计得很谨慎。它会过滤掉隐藏文件以.开头、可能包含凭证的文件如.env*.pem、被.gitignore忽略的文件并且拒绝发送大于50MB的文件。这既保护了你的敏感信息也避免了堵塞Telegram。4.4 实时终端视图与截图有时纯文本输出不够直观比如查看一个图表或复杂的UI布局。CCGram提供了两种“看”的方式终端截图使用/screenshot命令或点击操作栏的“Screenshot”按钮CCGram会捕获当前tmux窗格的画面生成一张PNG图片发送到聊天中。实时视图点击“Live”按钮CCGram会开始每5秒自动刷新并发送一张截图。这对于监控长时间运行的命令进度如构建、测试非常有用。为了节省资源它采用了内容哈希门控——如果连续两张截图的内容完全没变化就不会发送新消息。实时视图在5分钟无活动后会自动停止。4.5 提供者专属操作栏 (/toolbar)输入/toolbar命令Bot会发送一组针对当前AI提供者的快捷按钮。这相当于给你的手机屏幕增加了一排物理快捷键。通用行Screenshot截图、Ctrl-C中断、Live实时视图、Send发送文件。Claude专属行Mode切换模式、Think显示/隐藏思考过程、Esc发送Esc键。Codex/Gemini/Pi专属行Esc、Enter回车、Tab补全。Shell专属行Enter、EOF发送Ctrl-D、Suspend发送Ctrl-Z。在手机虚拟键盘上频繁输入Ctrl-C、Esc这类组合键很麻烦这个工具栏极大地提升了操作效率。5. Shell提供者将自然语言转化为命令行这是CCGram中一个独立且强大的子系统。它不依赖任何特定的AI编程助手CLI而是让你用自然语言与你的服务器Shell交互。工作原理你像聊天一样发送需求“找出最近一周修改过的日志文件并压缩它们。”CCGram将这条消息发送给你配置的LLM可以是OpenAI、Anthropic、Ollama本地模型等。LLM生成它认为最合适的Shell命令例如find /var/log -name *.log -mtime -7 -exec gzip {} \;这个命令会以按钮形式呈现在Telegram中并附上解释。你确认后命令才会在Shell中执行输出结果流式传回。两种模式聊天模式默认如上所述所有输入先经过LLM理解。原始模式在消息前加上感叹号!如!ls -la消息会绕过LLM直接作为Shell命令执行。这用于执行你明确知道的精确命令。危险命令检测Shell提供者内置了一个简单的危险命令列表如rm -rf /ddmkfs等。当LLM生成或你直接输入此类命令时CCGram会要求二次确认防止误操作。个人体会Shell提供者特别适合执行那些你记得大概但忘了具体参数的命令或者进行复杂的文件操作。它就像一个有求必应、但每一步都需要你点头的超级Shell助手。我常用它来清理Docker镜像、分析磁盘空间、批量重命名文件省去了在手机小屏幕上查手册的麻烦。6. 会话管理、恢复与多实例运维6.1 会话生命周期与状态管理CCGram将会话状态持久化在~/.ccgram/state.json中。这包括话题与tmux窗口的绑定关系、每个话题的最后读取位置等。因此重启CCGram服务不会丢失你的会话。会话的“健康状态”通过定期心跳和进程检查来维护。CCGram能识别几种状态活跃tmux窗口存在且目标进程如claude正在运行。已完成进程正常退出例如Claude任务结束。对应的Telegram话题会在AUTOCLOSE_DONE_MINUTES默认30分钟后自动关闭。已死亡tmux窗口存在但进程已结束例如被kill。话题会在AUTOCLOSE_DEAD_MINUTES默认10分钟后自动关闭。丢失tmux窗口已被手动删除。下次CCGram检查时会发现绑定失效并在话题中提示“会话丢失”提供恢复选项。6.2 手动创建会话与自动同步你并非一定要通过Telegram来创建会话。你也可以直接在终端里操作# 1. 启动一个新的tmux会话如果还没有 tmux new-session -d -s dev # 2. 在这个会话中创建一个新窗口并启动Claude Code tmux new-window -t dev -n my-claude-session cd ~/projects/my-app claude # 3. CCGram会在下次扫描时或立即取决于实现检测到这个新窗口。 # 4. 在Telegram群组中CCGram会自动创建一个与之对应的话题通常以窗口名命名。这种“双向同步”的能力非常灵活。你可以在电脑上快速启动一个任务然后出门手机立刻就能接管控。6.3 会话恢复机制当CCGram检测到会话死亡或丢失时它会在对应的Telegram话题中发送一个恢复键盘选项包括Fresh关闭旧会话在相同目录下启动一个全新的AI会话。Continue尝试重新启动相同的命令适用于codexgemini等支持恢复的CLI。Resume对于Claude Code尝试从它自动保存的JSONL历史记录中恢复上次对话如果钩子已安装。6.4 多实例运行与系统服务化对于24/7在服务器上运行建议将其设置为系统服务。首先创建一个系统服务文件以systemd为例sudo nano /etc/systemd/system/ccgram.service添加以下内容根据实际情况修改UserWorkingDirectory和环境变量路径[Unit] DescriptionCCGram Telegram Bot Afternetwork.target [Service] Typesimple Useryour_username WorkingDirectory/home/your_username EnvironmentPATH/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin EnvironmentFile/home/your_username/.ccgram/.env ExecStart/home/your_username/.local/bin/ccgram Restartalways RestartSec10 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target然后启用并启动服务sudo systemctl daemon-reload sudo systemctl enable ccgram.service sudo systemctl start ccgram.service sudo systemctl status ccgram.service # 检查状态排查技巧如果服务启动失败首先用journalctl -u ccgram.service -f查看日志。常见问题包括环境变量文件路径错误、.env文件权限问题不应被其他用户读取、或者Bot Token/User ID配置有误。7. 高级特性智能体间消息传递Swarm模式这是CCGram最令人兴奋的功能之一它允许不同tmux窗口中的AI助手相互通信、协作形成一个简单的“智能体集群”。核心概念每个绑定到CCGram的tmux窗口即每个AI助手会话都被视为一个智能体Agent。它们可以通过一个基于文件的“邮箱”系统发送和接收消息。工作原理假设你有两个窗口窗口AClaude负责API设计和窗口BCodex负责UI生成。Claude在分析过程中认为需要UI组件的信息。它可以通过执行一个特殊的命令或由CCGram的钩子触发来发送消息。消息被写入一个共享的邮箱目录~/.ccgram/mailbox/每个窗口有一个对应的“收件箱”文件。CCGram的“消息代理”会监视这些邮箱文件。当它发现窗口BCodex处于空闲状态并且有发给它的消息时就会将消息内容通过tmux send-keys注入到窗口B的输入中。Codex收到消息后开始工作完成后可以再回复给Claude。使用场景任务分发一个主规划智能体如Claude可以将子任务“编写用户登录函数”、“生成数据库迁移脚本”分发给其他更专业的智能体。信息同步UI智能体完成组件后可以通知后端智能体“用户模型接口已更新请调整相应的API端点”。生成新智能体一个智能体可以发起请求在另一个目录下启动一个新的AI会话来处理衍生任务这需要你在Telegram上点击确认。配置与启动 Swarm功能默认是开启的但需要智能体本身支持或被“教导”如何使用发送消息的命令通常是ccgram msg send。具体设置方法需要参考项目的docs/guides.md中关于Inter-Agent Messaging的章节。这通常涉及到在AI助手的初始化提示词Prompt中注入协作指令。个人经验Swarm模式目前还处于实验性阶段设置起来有些复杂需要对每个AI助手的提示词进行精细调教。但对于自动化复杂、多步骤的研发流程如“需求分析 - API设计 - 数据库建模 - 前端页面生成”它展现出了巨大的潜力。我主要用它来让Claude做架构师把具体的模块实现交给Codex和Gemini大大提升了并行开发的速度。