AI coding agent で一番困る瞬間は、agent が code を書き始めた時ではなく、走らせたまま人間が席を離れたい時だったりする。Build はまだ終わらない。Test が permission を聞くかもしれない。Agent が確認 prompt で止まるかもしれない。全部を remote service に任せる方法もあるが、実際の workflow はまだ local terminal に残っていることが多い。tmux session、project directory、未 commit の diff、shell environment、すでに起動している agent CLI。

今日見るのは alexei-led/ccgram。狙いはかなり狭い。Telegram と terminal multiplexer の橋になり、phone から Claude Code、Codex、Gemini、Pi、または普通の shell の出力を見て、返答を同じ terminal session に送り返す。特定の agent SDK を包む tool ではないし、新しい cloud conversation を作るものでもない。README の重要な設計点は、agent process は tmux、herdr、agterm の中に残り、terminal session が source of truth で、Telegram は remote control surface になる、ということだ。

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、license は MIT、default branch は main、repository 作成日は 2026-02-10 09:35:58 UTC、latest push は 2026-08-31 09:42:49 UTC。最新 commit は d8d1ef7、commit time は 2026-08-31 09:42:48 UTC、内容は multiplexer status test の environment isolation。Latest GitHub Release は v4.9.3、published time は 2026-08-31 09:40:08 UTC。pyproject.toml の package name は ccgram で、runtime requirement は Python 3.14+ だ。

プロジェクト概要

項目内容
リポジトリalexei-led/ccgram
位置づけTelegram から tmux / herdr / agterm へつなぐ terminal agent control bridge
Stars258
Forks75
主要言語Python
ライセンスMIT
作成日2026-02-10 09:35:58 UTC
Latest push2026-08-31 09:42:49 UTC
最新 commitd8d1ef7、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

terminal から離れた後の引き継ぎ

Telegram bot の中には agent API を chat window に包むものがある。その形は remote conversation を新しく始めるには便利だが、すでに local machine で走っている task を引き継ぐには向かない。Desktop に戻ったときには、元の tmux window に attach し、scrollback を見て、local editor、git、shell をそのまま使いたい。CCGram は逆の境界を選んでいる。Agent を terminal から外へ移すのではなく、terminal multiplexer の上に message channel を足す。

この設計では workflow が切れにくい。Desktop で起動した Codex や Claude Code は、元の project directory に残る。Environment variables、worktree、permission prompt、filesystem state は local machine の規則に従う。人間が席を離れた後、Telegram は output を受け取り続け、必要なら command、slash command、Enter、Esc、voice message を送れる。Desktop に戻ったら同じ session に attach すればよく、cloud chat の内容を手で local に同期する必要はない。

README にある topic mapping も実用的だ。Telegram group の forum topic は、tmux window、guarded Herdr agent session、または durable agterm session UUID に対応できる。複数 agent を同時に走らせる場合、api、ui、data、ops を別々の topic として扱える。一つの長い chat stream に全部を混ぜるより、実際の作業台に近い。

chat tool というより session safety tool

CCGram の README は delivery、sync、session binding にかなりの分量を割いている。これは単なる bot command の紹介より重要だ。長時間 agent を走らせると、message duplication、backlog、restart recovery、topic cleanup はすぐ実問題になる。ここを雑に扱う remote control tool は、新しい不確実性を持ち込む。

CCGram は raw provider transcript を保持し、Telegram delivery failure で message を静かに失わない。Delivery は at-least-once なので、restart や failure の後に transcript が重複することはあるが、成功したふりをして消えるよりはよい。Severe backlog では status bubble が live に飛ぶ確認 action を出し、skipped-range notice を残す。/sync は local record 上で条件を満たす retired topics だけを cleanup し、任意の Telegram topic を列挙して削除しない。

Herdr binding の説明からも、operation boundary を強く意識していることが分かる。CCGram は tab、pane、名前を恒久 ID として扱わず、agent.list の session identity を読む。Missing、malformed、legacy binding、duplicate canonical target は fail closed か quarantine される。この細かさは退屈に見えるが、remote から agent に input を送る tool では、間違った pane に command を送らないことが最重要になる。

install path は明確だが前提は軽くない

README の推奨 install は次の形だ。

uv tool install ccgram
# または pipx install ccgram / brew install alexei-led/tap/ccgram

その後、Telegram の BotFather で bot を作り、Topics を有効にした group に bot を追加して Admin にし、~/.ccgram/.env に TELEGRAM_BOT_TOKEN、ALLOWED_USERS、CCGRAM_GROUP_ID を設定する。ccgram を起動して Telegram topic に message を送ると、directory browser から project directory と provider を選べる。

これは「app を一つ入れれば終わり」の tool ではない。Telegram bot permission、group topic、tmux/herdr/agterm、local agent CLI の動き方を理解する必要がある。ただし、README はその複雑さを隠していない。明示的な設定として出している。Personal power user や小さな team なら、この透明さのほうが過度な自動化より扱いやすい。

Platform support も確認しておきたい。Linux、macOS、WSL2 は supported。Native Windows は unsupported だ。理由は自然で、CCGram は Unix file locking、signal handling、terminal multiplexer の機能に依存している。agterm backend は macOS-native。Windows user は WSL2 の中で tmux か herdr を使う形になる。

herdr とは別の層

Gumi では以前 herdr を取り上げた。あれは AI agent 専用の terminal workspace manager だ。CCGram は herdr に接続できるが、herdr を置き換えようとしているわけではない。より正確には、herdr が session と workspace を管理し、CCGram が remote message entry を管理する。tmux や agterm でも同じ関係だ。CCGram の価値は新しい terminal を設計することではなく、多くの人がすでに持っている terminal multiplexer に phone を接続することにある。

だから普通の通知 script より面白い。Notification は「出力があった」「task が終わった」と知らせるだけだ。CCGram は同じ topic から live view を見て、input を送り、session を recover し、workspace file を送信し、provider-specific toolbar で Screenshot、Mode、Esc、Enter のような action を実行できる。Remote control が片方向ではなく双方向になる。

向いている人

一つ目は、agent に長い task をよく任せる人だ。Codex に中規模 feature を触らせる、Claude Code に test cleanup を走らせる、Gemini CLI に document を調べさせる。PC の前に座り続けたくはないが、開発環境全体を cloud に移したいわけでもない。

二つ目は、tmux や herdr を好む local-first user だ。Session、scrollback、shell history、git state は local machine に残す。Telegram は一時的な control surface にする。この境界は source code、credential、local environment に敏感な workflow と相性がよい。

三つ目は、複数の agent session を同時に管理する人だ。Telegram forum topics と tmux window / herdr session / agterm UUID の mapping により、parallel task を分けやすく、返答を間違った場所に送る risk も下げられる。

Caveats

第一に、runtime requirement が新しい。pyproject.toml は Python 3.14+ を要求している。多くの system ではまだ default version ではないので、install 前に uv、pipx、Homebrew の Python path を確認したほうがよい。

第二に、Telegram 自体が operation boundary の一部になる。Bot token、group admin permission、allowed user ID、topic permission は慎重に設定する必要がある。Agent shell input を chat app に接続するということは、操作権限の一部を bot に渡すということだ。

第三に、terminal multiplexer の状態に依存する。tmux、herdr、agterm の session identity、pane state、background process がすでに混乱している場合、CCGram は上層で防御できても、下の作業台を整理してはくれない。最初は low-risk project と独立した topic から試すのがよい。

まとめ

alexei-led/ccgram が面白いのは、AI coding agent の remote control を新しい閉じた platform にしていないところだ。既存の terminal session の上に立ち、Telegram を observation、response、recovery の通路にする。Local terminal を開発の source of truth として残したい人には、かなり実用的な方向だ。

全員向けの軽い toy ではない。Python 3.14+、Telegram bot permission、tmux/herdr/agterm、agent CLI への理解が必要になる。それでも本当の pain が「agent は走っているが、自分は PC から離れたい」なら、CCGram はその隙間をちょうど埋める tool だ。

プロジェクトアドレス：https://github.com/alexei-led/ccgram