CCGram - Control AI Coding Agents from Your Phone via Telegram and tmux

#ai #opensource #coding #cli

AI coding agents — Claude Code, Codex CLI, Gemini CLI — run in your terminal. When you step away from your desk, the session keeps working, but you lose visibility and control. Especially when the agent hits a permission prompt or needs your input.

CCGram fixes this. It bridges Telegram to tmux so you can monitor and control your agents from your phone.

The key insight: operate on tmux, not on SDKs

Your agent runs in a tmux window on your machine. CCGram reads its transcript output and forwards it to a Telegram Forum topic. You type in Telegram — keystrokes go to the agent's tmux pane. Walk away from your laptop, keep the conversation going. Come back, tmux attach, full scrollback. Nothing lost.

Other Telegram bots wrap agent SDKs to create isolated API sessions that can't be resumed in your terminal. CCGram is different — it's a thin control layer over tmux.

One topic, one window, one agent

Each Telegram Forum topic binds to one tmux window running one agent session. You can run Claude Code, Codex CLI, and Gemini CLI in parallel across different topics.

Creating a session: open a Telegram topic, send any message. A directory browser appears — pick your project directory, choose the agent (Claude, Codex, or Gemini), choose the mode (Standard or YOLO), and you're connected.

Or create a tmux window manually, start an agent — CCGram auto-detects the provider and creates a matching topic.

Interactive prompts as inline keyboards

When your agent asks for permission, approval, or input, CCGram renders the prompt as Telegram inline keyboard buttons. Tap to approve — no typing "yes" or copying options.

This works across providers:

Claude Code: AskUserQuestion, ExitPlanMode, permissions
Codex: edit approvals (reformatted with compact summary + diff preview), selection prompts
Gemini: action-required prompts from @inquirer/select

Claude Code: deepest integration

Claude Code gets 7 hook event types — SessionStart, Notification, Stop, SubagentStart, SubagentStop, TeammateIdle, TaskCompleted. These provide instant session tracking and notifications rather than polling.

Multi-pane support for agent teams: blocked panes in non-active panes are auto-surfaced as inline keyboard alerts. /panes command shows all panes with status and per-pane screenshot buttons.

Session management

Recovery: when a session dies, the bot offers Fresh (new session), Continue (last conversation), or Resume (pick from past sessions). Buttons adapt to provider capabilities.
Sessions dashboard (/sessions): overview of all active sessions with status and kill buttons.
Message history (/history): paginated browsing of past messages.
Terminal screenshots: capture the current pane as a PNG image — useful for visual context.
Auto-close: done topics close after 30 minutes, dead sessions after 10. Configurable or disabled.
Provider commands: /commands shows all slash commands available for that topic's agent. Menus auto-switch per provider context.

Operations

Multi-instance: run separate bots per Telegram group on the same machine, sharing a single bot token. Each instance has its own tmux session, config, and state.
tmux auto-detection: start ccgram inside an existing tmux session — it discovers all agent windows, no creation needed.
Emdash integration: auto-discovers emdash-managed tmux sessions with zero configuration.
Diagnostics: ccgram doctor validates setup, checks hooks, finds orphan processes. ccgram doctor --fix auto-fixes.
Persistent state: thread bindings, read offsets, window states survive restarts.
Run as service: systemd unit, launchd plist, or detached tmux.

Install

  uv tool install ccgram

Alternatives: pipx install ccgram, brew install alexei-led/tap/ccgram

Configure a Telegram bot token via BotFather, enable Topics, add to a group, set your user ID in ~/.ccgram/.env, run ccgram.

For Claude Code, install hooks for best experience: ccgram hook --install

Links

GitHub: https://github.com/alexei-led/ccgram
PyPI: https://pypi.org/project/ccgram
Documentation: https://github.com/alexei-led/ccgram/blob/main/docs/guides.md

MIT licensed, Python. If you run AI coding agents and want mobile access without losing your terminal workflow — give it a try. Contributions and feedback welcome.

Hope you find this useful.