CCGram is a Telegram bridge for AI coding agents. Each Telegram Forum topic binds 1:1 to a terminal multiplexer window running Claude Code, Codex, Gemini, Pi, or a plain shell session. You monitor output, respond to interactive prompts via inline keyboards, and manage sessions — all from your phone while the agent runs on your machine.

The agent process stays in your local terminal session. Walk away from your desk, keep working from Telegram. Come back, attach to your terminal, and you have full scrollback exactly where the session left off.

v4.0.0 brings full herdr backend support.

What is herdr?

herdr is a modern terminal multiplexer with a workspace/tab model — like tmux, but organized around named workspaces and tabs rather than sessions and windows. It has a socket-based control API and native agent-status reporting built in.

If you use herdr and want ccgram to work with it: set one environment variable.

CCGRAM_MULTIPLEXER=herdr

Everything else — topics, providers, Claude hooks, session recovery, voice messages, screenshots, live view — works identically. The multiplexer is behind a Protocol seam in the codebase; callers never see which backend is active.

What changes when you use the herdr backend

Adaptive topic labels

On tmux, topics inherit the window name. On herdr, topics are labeled
"workspace ▸ tab" — e.g. "api ▸ auth-rewrite". The tab name is primary so two tabs in the same workspace still get distinct titles. If either part is missing, the label degrades gracefully to just the tab name or just the workspace name.

Workspace picker in /new

When you create a new session from Telegram, the flow gains an extra step on herdr: a workspace picker that lets you pin the new tab inside an existing workspace. If no workspaces exist yet, the step is skipped and ccgram creates a new one automatically.

Only agent tabs surface as topics

On tmux, every window is eligible to become a Telegram topic. On herdr, only tabs actively running an agent CLI (Claude Code, Codex, Gemini, Pi) are surfaced. A bare shell tab doesn't become a topic. This uses herdr's native agent-status capability — no terminal scraping required.

Native agent status

herdr reports what's running in a pane directly via pane process-info. ccgram doesn't need to scrape terminal output to figure out the active agent; it reads the structured data the multiplexer already provides.

Session re-resolution after restart

herdr re-mints tab IDs when its server restarts. ccgram handles this by re-mapping stale tab IDs to new ones via the shared session ID written by the Claude hook. Telegram topic bindings survive a herdr restart.

Protocol version pinning

ccgram pins the herdr socket protocol version it was built against and refuses to start on a mismatch, rather than silently misparsing changed JSON shapes.
If you upgrade herdr and see a protocol error, the ccgram build needs updating to match.

Same Claude Code hook

The hook that tracks sessions and fires events (SessionStart, Stop, interactive UI prompts) resolves which window fired from $HERDR_PANE_ID on herdr vs $TMUX_PANE on tmux. No herdr-specific hook setup is required.

Architecture: the multiplexer seam

The multiplexer access lives behind a Multiplexer Protocol in
multiplexer/base.py — a pure, I/O-free module with no backend imports.
Both tmux (multiplexer/tmux.py) and herdr (multiplexer/herdr.py) implement the same protocol and return the same neutral value types:

• WindowRef — a window/tab reference
• PaneInfo — pane metadata
• CaptureResult — scrollback capture with a truncation flag
• ForegroundInfo — the foreground process (pid, argv, cwd)

Callers import the module-level multiplexer proxy and type against the protocol — never a concrete backend. An architectural fitness test (tests/ccgram/test_multiplexer_boundary.py) enforces the boundary.

Quick start with herdr

# Install ccgram
uv tool install ccgram

# Set the backend
echo "CCGRAM_MULTIPLEXER=herdr" >> ~/.ccgram/.env

# Install Claude Code hooks (same as tmux)
ccgram hook --install

# Verify everything looks good
ccgram doctor

# Run
ccgram

Open your Telegram group, create a new topic, send a message — the directory browser appears. Pick a project directory, pick your agent, pick a workspace, and you're connected.

Install

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

Release notes: https://github.com/alexei-led/ccgram/releases/tag/v4.0.0
Source: https://github.com/alexei-led/ccgram