CCGram - Telegram Bridge for Remote Control of AI Coding Agents via tmux

1 min read
telegram-bottmuxclaude-codeai-agentsremote-controlcodex-cligemini-clideveloper-tools
Originally from github.com
View source

My notes

Summary

CCGram bridges Telegram to tmux sessions running AI coding agents (Claude Code, Codex CLI, Gemini CLI), letting you monitor output and respond to prompts from your phone. The key architectural decision is that it operates on tmux rather than wrapping agent SDKs, so the terminal session remains the source of truth and you can seamlessly switch between phone and desktop.

Key Insight

  • tmux-native approach beats SDK wrappers - by reading tmux output and injecting keystrokes rather than wrapping agent APIs, the tool avoids creating isolated sessions that can’t resume in a terminal. This is the core differentiator vs other Telegram bots.
  • Topic-per-session architecture - each Telegram Forum topic maps to a separate tmux window, enabling parallel agent sessions with different providers simultaneously (Claude in one topic, Codex in another, Gemini in a third).
  • Inter-agent messaging (swarm mode) - agents can discover each other, exchange messages, broadcast, and spawn new agents using a file-based mailbox at ~/.ccgram/mailbox/. No database or daemon required. User approves spawn requests via Telegram.
  • Shell provider with LLM command generation - plain shell topics accept natural language, route through any LLM (OpenAI, Anthropic, xAI, DeepSeek, Groq, Ollama), generate commands, and require one-tap approval before execution. Dangerous command detection adds an extra confirmation step.
  • Voice message support - Whisper API transcription (OpenAI or Groq) with confirm/discard keyboard, useful for voice-to-command workflows.
  • Claude Code hooks integration - ccgram hook --install registers hooks for SessionStart, Notification, Stop, StopFailure, SessionEnd, SubagentStart/Stop, TeammateIdle, and TaskCompleted for automatic tracking and instant prompt detection.
  • Emdash integration - auto-discovers emdash tmux sessions for zero-config binding of Telegram topics to emdash-managed agents.
  • Requires Python 3.14+, tmux, and at least one agent CLI installed.