CCGram — Control AI Coding Agents from Telegram

Control AI coding agents from your phone. CCGram bridges Telegram to tmux — monitor output, respond to prompts, and manage multiple sessions without touching your computer. Supports Claude Code, Codex CLI, Gemini CLI, Pi, and plain shell sessions.

Why CCGram?

AI coding agents run in your terminal. When you step away — commuting, on the couch, or just away from your desk — the session keeps working, but you lose visibility and control.

CCGram fixes this. It operates on tmux, not any agent SDK. Your agent process stays exactly where it is, in a tmux window on your machine. CCGram reads its output and sends keystrokes to it. This means:

• Desktop to phone, mid-conversation — walk away and keep monitoring from Telegram
• Phone back to desktop, anytime — tmux attach and you're back with full scrollback
• Multiple sessions in parallel — each Telegram topic maps to a separate tmux window, each running a different agent

Other Telegram bots wrap agent SDKs into isolated API sessions that can't be resumed in your terminal. CCGram is a thin control layer over tmux — the terminal stays the source of truth.

How It Works

graph LR
  subgraph phone["📱 Telegram Group (Forum Topics)"]
    direction TB
    T1["💬 api — Claude"]
    T2["💬 ui — Codex"]
    T3["💬 data — Gemini"]
    T4["💬 ops — Shell"]
    T5["💬 lab — Pi"]
  end

  subgraph bridge["⚡ CCGram"]
    direction TB
    B1["read output\n(transcripts + terminal)"]
    B2["send keystrokes\n(tmux send-keys)"]
    B3["instant notifications\n(Claude hooks)"]
  end

  subgraph machine["🖥️ Your Machine — tmux session"]
    direction TB
    W1["window @0 · claude"]
    W2["window @1 · codex"]
    W3["window @2 · gemini"]
    W4["window @3 · bash"]
    W5["window @4 · pi"]
  end

  phone -- "messages / voice" --> bridge
  bridge -- "responses / live view" --> phone
  bridge <--> machine

  style phone fill:#e8f4fd,stroke:#0088cc,stroke-width:2px,color:#333
  style bridge fill:#fff8e1,stroke:#f9a825,stroke-width:2px,color:#333
  style machine fill:#f0faf0,stroke:#2ea44f,stroke-width:2px,color:#333

Each Telegram Forum topic binds to one tmux window. Messages you type are sent as keystrokes to the pane; responses are parsed from session transcripts and delivered back as Telegram messages.

Features

Session Control

• Topic-per-agent — each Telegram Forum topic is one tmux window running one agent CLI
• Interactive prompts — AskUserQuestion, ExitPlanMode, and Permission dialogs rendered as inline keyboards
• Slash commands — provider-aware menu (Claude /cost, Codex /status, Gemini /chat, Pi /compact, etc.); mismatched commands report errors
• Voice messages — transcribed via Whisper API (OpenAI/Groq), shown with Send / Discard buttons before forwarding
• Multi-pane support — auto-detects blocked panes in agent teams, surfaces prompts as alerts; /panes for overview
• Terminal screenshots — capture the current pane (or any specific pane) as a PNG image
• Terminal live view — auto-refreshing screenshots every 5 seconds via Live button or /live command; content-hash gating skips edits when nothing changed; auto-stops after timeout (configurable)
• File delivery (/send) — send workspace files to Telegram: exact path (/send docs/arch.png), glob (/send *.png), substring search (/send arch), or interactive browser (/send). Project-scoped with security filtering (hidden files, credentials, gitignored, >50 MB denied)
• Action toolbar (/toolbar) — provider-specific inline buttons. Universal row: Screenshot, Ctrl-C, Live, Send. Provider row varies: Claude (Mode, Think, Esc), Codex (Esc, Enter, Tab), Gemini (Mode, YOLO, Esc), Pi (Esc, Enter, Tab), Shell (Enter, EOF, Suspend)
• Remote Control — 📡 topic badge when RC is active; one-tap activation from status keyboard

Real-Time Monitoring

• Full status context — status line shows what the agent is actually doing ("📝 Writing tests for auth module"), not a generic label
• Configurable topic emoji color scheme — CCGRAM_STATUS_MODE=system (default, green = agent working) or user (green = idle, ready for input) — pick the convention that matches how you scan the topic list
• Completion summaries — when an agent finishes, a single-line LLM summary of what was accomplished edits the Ready message in-place (~1-2s delay; static enriched Ready appears immediately)
• Enriched Ready message — task checklist, turn count, and last status shown on completion
• Tool results — tool use/result pairs, thinking content, Bash exit codes, and error/success indicators in batched output
• Tool-call visibility toggle — CCGRAM_HIDE_TOOL_CALLS=true globally hides tool_use/tool_result messages; /toolcalls cycles per-window (default → shown → hidden). Hook events (Stop, errors, subagent updates) bypass the gate
• Entity-based formatting — markdown converted to plain text + MessageEntity offsets; automatic plain text fallback, no parse errors

Session Management

• Directory browser — create sessions from Telegram by navigating your file system
• Auto-sync — create a tmux window manually and the bot auto-creates a matching topic
• Recovery — Fresh / Continue / Resume keyboard when a session dies (buttons adapt per provider)
• Message history — paginated browsing via /history
• Sessions dashboard — /sessions shows all active sessions with status and kill buttons
• Persistent state — bindings and read offsets survive bot restarts

Multi-Provider Support

graph TB
  subgraph providers["Agent Providers"]
    direction LR
    C["🟠 Claude Code\nhook events · resume · JSONL"]
    X["🧩 Codex CLI\nresume · continue · JSONL"]
    G["♊ Gemini CLI\nresume · continue · JSONL"]
    P["🥧 Pi\nresume · continue · JSONL"]
    S["🐚 Shell\nnl→command · raw mode"]
  end

  subgraph detection["Auto-Detection"]
    D1["process name\n(fast path)"]
    D2["ps -t tty\n(JS runtime fallback)"]
    D3["pane title symbols\n(Gemini fallback)"]
  end

  providers --> detection

  style providers fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#333
  style detection fill:#e8f4fd,stroke:#0088cc,stroke-width:2px,color:#333

• Per-topic provider — different topics can use different agents simultaneously
• Auto-detect — externally created tmux windows are detected via process name, with ps -t TTY fallback for JS runtime wrappers (node/bun)
• Emdash integration — auto-discovers emdash tmux sessions; bind Telegram topics to emdash-managed agents with zero configuration

Shell Provider

• Chat-first — type natural language → LLM generates a shell command → approve with one tap → output streams back
• Raw mode — prefix with ! to bypass the LLM and send commands directly
• Voice-to-command — voice messages transcribed via Whisper, then routed through the LLM
• Dangerous command detection — extra confirmation step before running destructive commands
• BYOK LLM — OpenAI, Anthropic, xAI, DeepSeek, Groq, Ollama (zero new dependencies)

Inter-Agent Messaging (Swarm)

graph LR
  subgraph agents["Agent Windows"]
    A1["claude · api"]
    A2["codex · ui"]
    A3["shell · ops"]
  end

  subgraph mailbox["~/.ccgram/mailbox/"]
    M["file-based\nper-window inboxes\nJSON messages · TTL"]
  end

  subgraph telegram["Telegram"]
    N["silent notifications\nin sender + recipient topics"]
    S["spawn approval\ninline keyboard"]
  end

  A1 -- "ccgram msg send" --> mailbox
  mailbox -- "broker injects\nvia send-keys" --> A2
  A3 -- "ccgram msg spawn" --> S
  mailbox --> N

  style agents fill:#f0faf0,stroke:#2ea44f,stroke-width:2px,color:#333
  style mailbox fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#333
  style telegram fill:#e8f4fd,stroke:#0088cc,stroke-width:2px,color:#333

• Agents discover each other, exchange messages, broadcast notifications, and spawn new agents
• File-based mailbox (~/.ccgram/mailbox/) — no database, no daemon
• Broker delivers pending messages to idle windows automatically
• Spawn approval requires Telegram keyboard confirmation
• See docs/guides.md for setup and usage

Quick Start

Prerequisites

• Python 3.14+
• tmux — installed and in PATH
• At least one agent CLI — claude (default), codex, gemini, or pi installed and authenticated (or use shell with no extra install)

Install

uv tool install ccgram          # recommended
pipx install ccgram             # pipx
brew install alexei-led/tap/ccgram  # Homebrew (macOS)

Configure

1. Create a Telegram bot via @BotFather
2. In BotFather settings:
   • Allow Groups: On
   • Group Privacy: Off (required to see all topic messages)
   • Topics: On
3. Add the bot to a Telegram group with Topics enabled
4. Promote the bot to Administrator with **Create Topi