CCGram CLI
A Telegram bridge for Claude Code, Codex, Gemini and Pi terminal agents: sessions stay in the terminal, replies come from a phone.
- 286 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- A Telegram message starts the agent in YOLO mode and sends keystrokes to the terminal: code runs on your machine.
- The bot token and the `ALLOWED_USERS` list live in `~/.ccgram/.env`; bot access equals session access.
- Transcripts and terminal screenshots go to Telegram.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/ccgramDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- A Telegram message starts the agent in YOLO mode and sends keystrokes to the terminal: code runs on your machine.
- The bot token and the `ALLOWED_USERS` list live in `~/.ccgram/.env`; bot access equals session access.
- Transcripts and terminal screenshots go to Telegram.
This is third-party code. Review the repository files before installing.
What it does
CCGram sits on top of tmux, herdr or agterm and does not wrap agent SDKs. The agent stays in your terminal while each Telegram topic is bound to one window or session. The bot reads transcripts and terminal output, sends replies and screenshots, and types keystrokes. A session starts with one line such as `codex ccgram fix the hook timeout`. The bot finds the project, launches the agent and forwards the instruction. Voice messages are transcribed through Whisper, and buttons answer confirmation prompts with one tap.
Who it is for. Developers with long Claude Code or Codex sessions who step away from the computer and want to watch and answer the agent from Telegram.
Good fit when
- An agent builds a project for an hour and you want to see the result without sitting at the monitor.
- A confirmation prompt arrives while you are on the road and you want to answer with a button.
- Claude Code, Codex and Gemini run in parallel in different tmux windows.
- A task for the agent has to be given by voice from a phone.
Not a fit when
- There is no terminal multiplexer and none is planned: tmux, herdr or agterm is required.
- Native Windows without WSL2 is used: it is not supported.
- An isolated API bot without terminal access is wanted: CCGram controls a live session.
Example request
In a Telegram topic send `claude:safe myproject refactor the parser` and screenshot the terminal when the agent asks for confirmation.Limitations
Python 3.14 or newer, one multiplexer (tmux, herdr, agterm) and an agent CLI are required. Linux, macOS and WSL2 are supported; native Windows is not, and agterm runs on macOS only. Delivery is at-least-once, so a message may repeat after a failure. With herdr delivery is not atomic: a session can change between the check and the send. The bot needs a token from @BotFather and an `ALLOWED_USERS` list in `~/.ccgram/.env`.
How to disable. Stop the `ccgram` process, revoke the bot token in @BotFather and remove the package with `uv tool uninstall ccgram`. Delete the hooks installed by `ccgram hook --install` from the Claude Code settings.
FAQ
How does a CCGram session differ from an agent SDK bot?
The agent lives in your tmux, herdr or agterm. You can pick the session up in the terminal with full output history.
How do I start a new session?
Create a topic in Telegram and send a line `<agent>[:<mode>] <project|path> [@branch] <instruction...>`. `/bind` adopts an already running window.
Which agents are supported?
Claude Code, Codex, Gemini, Pi and a plain shell. The provider is detected automatically, and `/agent` shows and changes the choice.
Does CCGram work on Windows?
Only inside WSL2. Native Windows is not supported: it lacks file locking, signals and terminal multiplexers.
How do I connect Claude Code hooks?
Run `ccgram hook --install`. The `SessionStart` and `Stop` hooks are asynchronous; re-run the command after upgrading, and no duplicates appear.
Discussion
No questions or reviews yet.
Related
CLI toolsA bridge linking WeChat, WeCom or Telegram with local Codex, Claude Code, OpenCode and Pi so the agent can be driven from a phone.
A terminal workspace where several CLI agents like Codex, Claude and Gemini exchange messages and work on one task under human oversight
The MetaBot CLI connects local coding agents to messaging and a web console while retaining tasks and sessions
A Telegram bridge for the Pi coding agent: continue sessions from your phone and hand them back to the terminal
botmux connects Lark and Feishu to Claude Code, Codex, Gemini CLI and OpenCode: each message starts its own agent session with live cards
ccmux tracks every coding agent in tmux: who is working, who waits for you, worktree spawning and answer hand-off.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| CCGram (this card) | no | 286 | |
| tlive | no | 214 | a standalone service for monitoring and approving actions in Telegram, Feishu and a web terminal; CCGram binds Telegram topics to tmux, herdr and agterm windows |
| OpenCode Telegram Bot | no | 1,339 | a Telegram bot for the single OpenCode agent; CCGram drives Claude Code, Codex, Gemini and Pi in one topic group |
README in short
Install with `uv tool install ccgram`; Claude Code hooks come from `ccgram hook --install`. The README has separate setup sections for herdr and agterm.