tg-bridge-channel

Self-hosted Telegram bridge for AI coding agents — the chat IS the terminal.

Drive Claude Code / Codex / Gemini from a Telegram chat, backed by claude --bg Agent View background sessions for subscription-billed Claude Code, and the A2A-TG envelope protocol for multi-agent collaboration in group chats.

English | 简体中文

---

What it is

tg-bridge-channel runs AI coding agents as Telegram bots. Each bot is a full agent session you talk to from your phone or desktop — the chat is the terminal. It supports three modes:

• Single-agent control — one Claude Code / Codex / Gemini session per bot, driven over Telegram.
• Parallel sessions — N independent bots in one group, each its own session, with shared context (SQLite/Redis).
• Heterogeneous multi-agent collaboration (experimental, disabled by default — set a2aEnabled to opt in) — Claude, Codex, and Gemini bots talking to each other in a group via the A2A-TG envelope protocol, with generation-counted loop suppression.

Engine layer

The claude backend ships two interchangeable engine implementations, selected at runtime by the CLAUDE_POOL_ENGINE environment variable:

Mode	Implementation	How it works
default	adapters/claude.js	Programmatic adapter built on the Claude Agent SDK.
CLAUDE_POOL_ENGINE=1	adapters/cli-pool-adapter.js	Per-chat claude --bg background sessions (Agent View).

The pool engine starts a claude --bg background session per Telegram chat. Each bot is one user driving multiple long-running Agent View sessions; inbound Telegram messages drive the sessions the same way you would from claude agents peek-reply, and outbound responses are read back from each session's local Claude Code transcript file.

The backend name stays claude in both modes, so all orchestration (backendName === "claude" checks for approval / labels / A2A / cron) is unchanged. Switching engines is a per-process environment variable; rolling back is removing it.

The pool engine relies on the official claude Agent View infrastructure: the per-user supervisor / spare-process warmup, the local ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl transcript files, and the subscription-usage billing that Anthropic documents for background sessions. It does not install plugins, does not change credentials, and does not bypass any quota — each background session counts toward your Claude subscription usage just like an interactive session you opened yourself.

An earlier interactive channel-plugin engine (CLAUDE_CHANNEL_ENGINE=1) used a local Model Context Protocol server modeled on Claude Code's built-in fakechat channel. It was removed in May 2026 in favor of the Agent View based pool engine; see git history before May 2026 for the channel-plugin engine implementation.

Quick start

# 1. install dependencies
bun install

# 2. configure
cp config.example.json config.json
# edit config.json: set ownerTelegramId and backends.<engine>.telegramBotToken

# 3. run (default SDK engine)
bun run start --backend claude --config config.json

To run the pool engine (recommended; subscription-billed background sessions):

CLAUDE_POOL_ENGINE=1 bun run start --backend claude --config config.json

Multi-instance

Each bot instance uses its own config file (config.json, config-2.json, …) with a distinct bot token and sessions database. Launch agent templates for always-on operation live in launchd/.

Configuration

See config.example.json for the full schema. Key fields:

• ownerTelegramId — only this user can drive the bot.
• backends.<claude|codex|gemini>.telegramBotToken — bot token per backend.
• sharedContextBackend — sqlite or redis for cross-bot shared memory.
• a2aEnabled / a2aPorts — enable A2A-TG inter-bot messaging.

A2A-TG protocol

The inter-bot envelope protocol is specified in docs/a2a-tg-v1.md. It is inspired by — but not compatible with — the official A2A protocol; it adds generation-based loop suppression and chat-scoped idempotency for the IM scenario.

Tests

bun test

Ecosystem

• telegram-ai-bridge — original Telegram bridge using A2A-TG protocol
• wechat-ai-bridge — same idea on WeChat
• recallnest — shared memory MCP across Claude/Codex/Gemini

License

MIT — see LICENSE.