电报AI桥梁

Recommended Deployment

Run multiple bots for parallel workflows:

• @cc-alpha → Claude Code instance 1 (primary)
• @cc-beta → Claude Code instance 2 (parallel tasks)
• @cc-gamma → Claude Code instance 3 (parallel tasks)
• @your-codex-bot → Codex (different backend)

Each Claude instance shares memory automatically. No configuration needed — CC's memory lives in ~/.claude/, not in the bot.

Supported backends:

Gemini's niche in this setup. The Gemini backend is best used as an overnight note-taker in a multi-agent group: let Claude and Codex brainstorm, and have Gemini read along and summarize the conversation on a schedule. It is the least chatty of the three backends, which turns out to be a fit for that role. Nothing in the code enforces a read-only mode — you shape the behavior through the per-bot CLAUDE.md / prompt. It runs through Gemini Code Assist API, not a full CLI terminal, so capabilities are narrower than Claude Code or Codex.

Core rule: One bot = one process = one independent agent. Run as many as you need.

The bridge is transparent. Your TG bot inherits whatever skills, MCP servers, and hooks your local CC has. If CC can browse the web, generate images, or query databases in terminal — it can do the same through Telegram. The bridge adds session management; the capabilities come from CC itself.

---

Multi-Instance Deployment

Run N parallel Claude Code instances, each with its own Telegram bot:

1. Create a bot — message @BotFather on Telegram, get a token.

2. Create a config file — copy and customize:

```bash cp config.json config-2.json

Quick Start

Prerequisites: Bun runtime, a Telegram bot token (from @BotFather), and at least one backend CLI: Claude Code, Codex, or Gemini CLI.

git clone https://github.com/AliceLJY/telegram-ai-bridge.git
cd telegram-ai-bridge
bun install
bun run bootstrap --backend claude
bun run setup --backend claude
bun run check --backend claude
bun run start --backend claude

Want parallel agents? Add a second bot in 30 seconds — see Multi-Instance Deployment.

Bidirectional Media — Screenshots & Files Flow Back

Input has always been bidirectional: text, photos, documents, voice all flow to CC. Now output is too:

• Screenshots: CC takes a screenshot → image appears in your TG chat automatically
• Files: CC creates or references a file → bridge detects the path and sends it as a TG attachment
• Long code: Output >4000 chars with >60% code → sent as a file attachment with preview summary

The bridge captures images from SDK tool results (base64 data from Read/peekaboo/screenshot tools) and scans CC's response text for file paths. No manual copy-paste, no "where did you save it?" — files just appear in the chat.

Reply to cancel: Task taking too long? Send /cancel to abort. Need context from a previous message? Reply to it — the quoted text is automatically included as context.

Edit config-2.json: change telegramBotToken, sessionsDb, tasksDb

**3. Start it:**

**4. (Optional) Register as LaunchAgent** for auto-start:

See the LaunchAgent section below for plist setup.

> **What's shared vs isolated:**
>
> | Shared (automatic) | Isolated (per-instance) |
> |---|---|
> | `~/.claude/` (CLAUDE.md, memory, skills, hooks) | Telegram bot token |
> | MCP servers (memory-store, etc.) | SQLite sessions DB |
> | Project settings & rules | SQLite tasks DB |
> | Git repos & file system | Log files |

---

<details>
<summary><strong>macOS LaunchAgent</strong></summary>

Generate and install:

The wrapper runs `bun run check` before `bun run start`, so bad config fails fast.
Logs are written under `~/Library/Logs/telegram-ai-bridge/` and the rotation agent copy-truncates them daily at 03:00.

Default labels: `com.telegram-ai-bridge`, `com.telegram-ai-bridge-codex`, `com.telegram-ai-bridge-gemini`.

If you see `409 Conflict`, another process is polling the same bot token.

</details>

<details>
<summary><strong>Docker</strong></summary>

docker run -d \ --name tg-ai-bridge-claude \ -v $(pwd)/config.json:/app/config.json:ro \ -v ~/.claude:/root/.claude \ telegram-ai-bridge --backend claude ```

Swap credential mount and --backend for other backends. See docker-compose.example.yml for a Compose starter.

</details>

<details> <summary><strong>Project Structure</strong></summary>

• start.js — CLI entry for start, bootstrap, check, setup, config
• config.js — Config loader and setup wizard
• bridge.js — Telegram bot runtime
• sessions.js — SQLite session persistence
• discuss-mode.js — Discuss mode send/silent contract, control command semantics, and probe gating
• group-context-pipeline.js — Canonical group-message context reduction and rendering
• telegram-command-routing.js — Telegram slash-command target parsing, including mention-first control commands
• streaming-preview.js — Live text preview via editMessage (throttled, with degradation)
• progress.js — Progress messages and typing-only indicators
• send-retry.js — Outbound delivery retry with error classification and HTML fallback
• file-ref-protect.js — Prevents Telegram auto-linking filenames as domains (.md, .go, .py etc.)
• shared-context.js — Cross-bot shared context entry point
• shared-context/ — Pluggable backends (SQLite / JSON / Redis)
• a2a/ — Agent-to-agent communication bus, loop guard, peer health
• adapters/ — Backend integrations
• launchd/ — LaunchAgent template for macOS
• scripts/ — Install wrapper and runtime launcher
• docker-compose.example.yml — Compose starter

</details>

<details> <summary><strong>Execution Modes</strong></summary>

• direct — runs the backend adapter in-process (default)
• local-agent — communicates with a local agent subprocess over JSONL stdio

Set in config.json at shared.executor, or override with BRIDGE_EXECUTOR.

</details>

---

In Codex: register Claude Code as MCP server (in ~/.codex/config.toml)

[mcp_servers.claude-code] type = "stdio" command = "claude" args = ["mcp", "serve"] ```

Terminal: CLI-to-CLI via MCP (No Telegram Needed)

Claude Code and Codex each have a built-in MCP server mode. Register them with each other and they can call each other directly — no bridge, no Telegram, no custom code:

```bash

How It Compares

Claude Code now ships Remote Control (Feb 2026) and a Telegram channel plugin (Mar 2026). Both let you talk to Claude from your phone. Neither gives you session management, multi-backend support, or agent-to-agent collaboration.

What official tools do better: Remote Control streams full terminal output. Channels relay tool-approval dialogs natively. This project optimizes for a different job: persistent, multi-agent session management entirely from Telegram.

<details> <summary><strong>Full comparison (26 features)</strong></summary>

</details>

<details> <summary><strong>Migrating from OpenClaw?</strong></summary>

Every OpenClaw feature has a direct equivalent — most of them are just CC running natively behind the bridge:

The difference: OpenClaw reimplements these features on top of an API. This project runs actual Claude Code — every feature CC has, you get for free.

</details>

---

Storage Backend Comparison

Set sharedContextBackend in config.json:

{
  "shared": {
    "sharedContextBackend": "redis",
    "redisUrl": "redis://localhost:6379"
  }
}

Note: Bots only respond when explicitly @mentioned or replied to. They don't auto-reply to each other.