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
• Git worktree topics — when a new topic's directory is an eligible git repo, you can spin the agent up in a fresh worktree on a new branch (suggested ccg/<topic-title>, one-tap confirm or edit the name) instead of the current branch; non-git directories see the unchanged flow
• Interactive prompts — AskUserQuestion, ExitPlanMode, and Permission dialogs rendered as inline keyboards
• Slash commands — provider-aware menu (Claude /cost, Codex /status, Gemini /chat, Pi /new, /compact, /scoped_models, etc.); Pi also supports /followup <message> to queue Pi's Alt+Enter follow-up message; 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 readable PNG of the current viewport, with ANSI color
• Last reply (/last, 📄 Last button) — resends the most recent assistant reply (AI providers, from the transcript) or last command+output (shell topics); long responses overflow to a .txt attachment instead of a giant 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. Row 1 is universal (Screenshot, Ctrl-C, Live). Row 2 varies per provider: Claude (Mode, Think, Esc), Codex (Esc, Tab, Mode), Gemini (Mode, YOLO, Esc), Pi (Esc, Tab, π Model), Shell (Enter, EOF, Suspend). Claude/Codex/Gemini/Pi add a universal navigation row (Up, Enter, Down). The final row is Last, Get File, Close (Shell folds Esc in: Last, Get File, Esc, Close). Customize via ~/.ccgram/toolbar.toml
• Picker hints — when you forward a slash command that opens a modal in-TUI picker (e.g. /model, /login, /theme), the topic reply suggests using /toolbar to drive the picker with arrow keys
• Remote Control — 📡 topic badge when RC is active; activate by forwarding /remote-control (or /rc) to the agent. Claude's /remote-control is silent on outcome, so ccgram probes the pane afterward and posts the result (sharing URL on success, "unavailable", or failure) as a single status reply (Claude only)

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 — tool_use/tool_result messages are shown by default; CCGRAM_HIDE_TOOL_CALLS=true suppresses them globally and /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)

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)

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