cc-telegram-bridge

RULE 1: Let your Claude Code or Codex CLI set this up for you. Clone the repo, open it in your terminal, and tell your AI agent: "read the README and configure a Telegram bot for me". It will handle the rest.

Dual Engine: Codex + Claude Code

Each bot instance can run either OpenAI Codex or Claude Code as its backend. Switch engines per-instance with one command:

# Set an instance to use Claude Code
npm run dev -- telegram engine claude --instance review-bot

# Set another to use Codex
npm run dev -- telegram engine codex --instance helper-bot

# Check current engine
npm run dev -- telegram engine --instance review-bot

| Feature | Codex Engine | Claude Engine | |---|---|---| | CLI command | codex exec --json | claude -p --output-format json | | Session resume | codex exec resume --json <id> | claude -p -r <session-id> | | Project instructions | agent.md (prepended to prompt) | agent.md (via --system-prompt) + CLAUDE.md (auto-loaded from workspace) | | YOLO mode | --full-auto / --dangerously-bypass-approvals-and-sandbox | --permission-mode bypassPermissions / --dangerously-skip-permissions | | /compact | Not needed (each exec is stateless) | Compresses session context to reduce token usage | | Working directory | workspace/ under instance dir | workspace/ under instance dir (with CLAUDE.md) |

Claude Engine: CLAUDE.md Support

When using the Claude engine, each instance gets a workspace/ directory. Drop a CLAUDE.md in there for project-level instructions that Claude Code reads natively:

~/.cctb/review-bot/
├── agent.md              ← "You are a strict code reviewer"
├── workspace/
│   └── CLAUDE.md         ← "TypeScript project. Use ESLint. Never modify tests."
├── config.json           ← { "engine": "claude", "approvalMode": "full-auto" }
└── .env

Two layers of instructions, no conflict:

• agent.md → Your bot personality (injected via --system-prompt)
• CLAUDE.md → Project rules (Claude auto-discovers from working directory)

Multi-Bot Setup

Run as many bots as you need. Each instance is fully isolated — its own engine, token, personality, threads, access rules, inbox, and audit trail.

          ┌─────────────────────────────────────────────┐
          │          cc-telegram-bridge              │
          └────────────┬──────────────┬─────────────────┘
                       │              │
        ┌──────────────┼──────────────┼──────────────┐
        ▼              ▼              ▼              ▼
 ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
 │  "default" │ │   "work"   │ │ "reviewer" │ │ "research" │
 │  engine:   │ │  engine:   │ │  engine:   │ │  engine:   │
 │   codex    │ │   codex    │ │   claude   │ │   claude   │
 │            │ │            │ │            │ │            │
 │ agent.md:  │ │ agent.md:  │ │ agent.md:  │ │ agent.md:  │
 │ "General   │ │ "Reply in  │ │ "Strict    │ │ "Deep      │
 │  helper"   │ │  Chinese"  │ │  reviewer" │ │  research" │
 └────────────┘ └────────────┘ └────────────┘ └────────────┘
   PID 4821       PID 5102       PID 5340       PID 5520

Deploy in 30 Seconds

# Configure each instance
npm run dev -- telegram configure <token-A>
npm run dev -- telegram configure --instance work <token-B>
npm run dev -- telegram configure --instance reviewer <token-C>

# Set engines
npm run dev -- telegram engine claude --instance reviewer

# Set personalities
npm run dev -- telegram instructions set --instance reviewer ./reviewer-instructions.md

# Enable YOLO for mobile use
npm run dev -- telegram yolo on --instance work

# Start them all
npm run dev -- telegram service start
npm run dev -- telegram service start --instance work
npm run dev -- telegram service start --instance reviewer

Agent Instructions

Each bot has its own agent.md. Hot-reloaded on every message — edit anytime, no restart needed.

npm run dev -- telegram instructions show --instance work
npm run dev -- telegram instructions set --instance work ./my-instructions.md
npm run dev -- telegram instructions path --instance work

Or edit directly:

# Windows
notepad %USERPROFILE%\.cctb\work\agent.md

# macOS
open -e ~/.cctb/work/agent.md

YOLO Mode

npm run dev -- telegram yolo on --instance work      # Safe auto-approve
npm run dev -- telegram yolo unsafe --instance work   # Skip ALL checks
npm run dev -- telegram yolo off --instance work      # Normal flow
npm run dev -- telegram yolo --instance work          # Check status

| Mode | Codex | Claude | Use case | |---|---|---|---| | off | Normal approvals | Normal approvals | Default, safest | | on | --full-auto | --permission-mode bypassPermissions | Mobile use | | unsafe | --dangerously-bypass-* | --dangerously-skip-permissions | Trusted env only |

Usage Tracking

Track token consumption and cost per instance:

npm run dev -- telegram usage                    # Default instance
npm run dev -- telegram usage --instance work    # Named instance

Output:

Instance: work
Requests: 42
Input tokens: 185,230
Output tokens: 12,450
Cached tokens: 96,000
Estimated cost: $0.3521
Last updated: 2026-04-09T10:00:00Z

Claude reports exact USD cost. Codex reports tokens only (cost shows as "unknown").

Verbosity Control

Control how much streaming progress you see:

npm run dev -- telegram verbosity 0 --instance work   # Quiet — no live updates
npm run dev -- telegram verbosity 1 --instance work   # Normal — update every 2s (default)
npm run dev -- telegram verbosity 2 --instance work   # Detailed — update every 1s
npm run dev -- telegram verbosity --instance work      # Check current level

Stored in config.json, hot-reloadable.

Budget Control

Set a per-instance spending cap. When total cost reaches the limit, new requests are blocked until the budget is raised or cleared.

npm run dev -- telegram budget show --instance work     # Current spend vs limit
npm run dev -- telegram budget set 10 --instance work   # Cap at $10
npm run dev -- telegram budget clear --instance work    # Remove cap

Budget is enforced in real-time — the bot replies with a bilingual message when the limit is hit.

Voice Input (ASR)

Send voice messages in Telegram — the bridge transcribes them locally before forwarding the text to the AI engine. No cloud ASR service required.

How it works:

1. User sends a voice message in Telegram
2. The bridge downloads the .ogg file
3. Transcribes it via a local ASR service (HTTP first, CLI fallback)
4. The transcript replaces the voice attachment as the user's text message
5. The AI engine processes it as a normal text request

Setup with Qwen3-ASR (example):

# Clone and install the ASR model
git clone https://github.com/nicoboss/qwen3-asr-python
cd qwen3-asr-python
python -m venv venv
source venv/bin/activate
pip install -e .

# Download a model (0.6B is fast enough for voice messages)
huggingface-cli download Qwen/Qwen3-ASR-0.6B --local-dir models/Qwen3-ASR-0.6B

The bridge looks for the ASR service at two locations (in order):

| Method | Endpoint / Path | Latency | Notes | |---|---|---|---| | HTTP server | POST http://127.0.0.1:8412/transcribe | ~2-3s | Model stays in memory. Recommended. | | CLI fallback | ~/projects/qwen3-asr/transcribe.py <file> | ~30s | Loads model each time. No server needed. |

Start the HTTP server (recommended):

python ~/projects/qwen3-asr/server.py
# Qwen3-ASR server listening on http://127.0.0.1:8412

**Custom ASR integr