CCGram — Control AI Coding Agents from Telegram

Control AI coding agents from your phone. Walk away mid-session. Keep monitoring and responding from Telegram—without losing terminal access.

Why CCGram?

AI coding agents run in your terminal. Other Telegram bots wrap agent SDKs into isolated API sessions you can't resume in your terminal. CCGram is different. It sits on top of your terminal multiplexer (tmux or herdr), not any agent SDK. Your agent process stays exactly where it is—your session is the source of truth.

This means:

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

---

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 / herdr)"]
    B3["instant notifications\n(Claude hooks)"]
  end

  subgraph machine["🖥️ Your Machine — tmux / herdr"]
    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

Loading

Each Telegram topic maps to one multiplexer window. Type in Telegram → keystrokes to pane → agent output back to Telegram.

---

What You Can Do

• Bind agents to topics — one agent per Telegram topic; create via directory browser
• Auto-detect providers — Supports Claude Code, Codex, Gemini, Pi, and Shell simultaneously
• Monitor live — Terminal screenshots on demand or auto-refresh every 5 seconds
• Send commands — Slash commands, voice messages (transcribed via Whisper), or raw shell input
• Run multiple agents in parallel — each topic independent; run different agents at once
• Recover gracefully — Resume, continue, or start fresh if a session crashes
• Send workspace files — Share files to Telegram via /send (glob, path, or substring search)
• Action toolbar — Provider-specific buttons for common actions (Screenshot, Mode, Esc, Enter, etc.)

---

Quick Start

Install:

uv tool install ccgram          # recommended
# or: pipx install ccgram | brew install alexei-led/tap/ccgram

Telegram setup:

1. Create a bot via @BotFather — full instructions
2. Add bot to a Telegram group with Topics enabled; promote to Admin
3. Create ~/.ccgram/.env:

TELEGRAM_BOT_TOKEN=your_bot_token_here
ALLOWED_USERS=your_telegram_user_id
CCGRAM_GROUP_ID=your_telegram_group_id

Get user ID from @userinfobot. Get group ID via @RawDataBot (prefix Peer ID with -100).

Run:

ccgram

Open your Telegram group, create a topic, send a message — directory browser appears. Pick a project directory, choose your agent (Claude, Codex, Gemini, Pi, or Shell), and you're connected.

Prerequisites: Python 3.14+, tmux or herdr (CCGram controls a terminal multiplexer; no agent SDK modifications needed), and one agent CLI (claude, codex, gemini, pi installed and authenticated, or use shell with no extra install).

---

Documentation

• Guides — CLI reference, configuration, voice transcription, multi-instance setup, session recovery, testing
• Providers — Claude Code, Codex, Gemini, Pi, Shell; session modes, LLM config, custom commands, git worktrees

---

Optional Features

Web Dashboard — Live terminal (xterm.js), transcript search, multi-pane grid in Telegram. Disabled by default. Enable here.

---

Development

git clone https://github.com/alexei-led/ccgram.git && cd ccgram
uv sync --extra dev
make check         # lint, format, typecheck, test
make test-e2e      # end-to-end tests (requires agent CLIs; see docs/guides.md#e2e-tests)

---

License

MIT