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, herdr, or agterm), 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 tmux window, guarded Herdr agent session, or agterm agent pane

---

How It Works

graph LR
  subgraph phone["📱 Telegram Topics (Group or Private Chat)"]
    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 / agterm)"]
    B3["instant notifications\n(Claude hooks)"]
  end

  subgraph machine["🖥️ Your Machine — tmux / herdr / agterm"]
    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 topic maps to one tmux window. With Herdr, it maps instead to one guarded agent session: agent.list is the sole identity source and CCGram persists only an opaque herdr-session-v1-… target, never a tab, pane, or terminal ID. Every Herdr agent topic is provider-prefixed and pane-qualified as ▸ <workspace> ▸ <tab> ▸, so Pi, Claude, Codex, and Gemini topics are easy to find while their labels remain stable when siblings join or leave the tab. Every action reads a fresh agent.list record and fails closed for missing, malformed, sessionless, or legacy bindings. Duplicate canonical targets are quarantined while unrelated sessions remain operational. Legacy locator bindings require explicit rebind and are never inferred from names. A session can still change after that guard and before Herdr dispatches, so delivery is not atomic and may be indeterminate after this post-guard race. With agterm, the primary topic retains the session UUID; split peers get separate foreground-guarded targets.

---

What You Can Do