cc-telegram-bridge - Codex & Claude Code on Telegram

The honest one-liner from the README is the right framing: this is not an API wrapper, it is the actual Codex or Claude Code CLI exposed through Telegram. Native sessions, real tool use, real local files. You can resume a desktop session from your phone, run isolated multi-bot teams, or fire off a long-running task and let it message you back when it's done.

The "RULE 1" the project leads with is also unusually self-aware: clone the repo, open it in Codex or Claude Code, and tell the agent "read the README and configure a Telegram bot for me." The bridge is built to be set up by the agent that's about to run inside it.

Dual engine: Codex + Claude Code

Each bot instance picks one engine and sticks with it. Switch with one command:

npm run dev -- telegram engine claude --instance review-bot
npm run dev -- telegram engine codex --instance helper-bot
npm run dev -- telegram engine --instance review-bot   # check current

The differences between the two backends are real and worth knowing:

The Codex per-turn approval is a CLI limit, not a design choice - codex exec doesn't support mid-turn approval callbacks, so the bridge approves the turn up front and runs it under --full-auto.

Multi-bot setup

Each instance is fully isolated: its own engine, token, personality, threads, access rules, inbox, and audit trail. By default an instance is meant for one Telegram chat; multi-chat access is opt-in.

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>

npm run dev -- telegram engine claude --instance reviewer
npm run dev -- telegram instructions set --instance reviewer ./reviewer-instructions.md
npm run dev -- telegram yolo on --instance work

npm run dev -- telegram service start
npm run dev -- telegram service start --instance work
npm run dev -- telegram service start --instance reviewer

agent.md is hot-reloaded on every message - edit anytime, no restart needed.

The directory layout per instance is opinionated and useful:

~/.cctb/review-bot/
├── agent.md              ← bot personality, e.g. "strict code reviewer"
├── workspace/
│   └── CLAUDE.md         ← project rules Claude auto-discovers
├── config.json           ← { "engine": "claude", "approvalMode": "full-auto" }
└── .env

Two layers of instructions, no conflict: agent.md is the bot's personality (injected as system prompt), CLAUDE.md is project rules (Claude reads it natively from the working directory).

YOLO mode

For mobile use, telegram yolo on is the recommended runtime. With YOLO off, the bridge can route per-permission Claude prompts (or per-turn Codex approval) back to Telegram as approval buttons. With unsafe, all checks are skipped - intended only for fully trusted local machines.

The Claude approval-button path uses a short-lived localhost MCP bridge with a random URL token. That defends against blind local port scans, but the token is visible to other same-user local processes that can read process command lines. Treat YOLO-off approval as a single-user workstation convenience, not a multi-user isolation boundary.

File delivery from agent tasks

During each active Telegram turn, the bridge injects a cctb command into the engine's PATH. Agents call it directly when they finish a generated file:

cctb send --image /absolute/path/to/image.png
cctb send --file /absolute/path/to/report.pdf
cctb send --message "Done" --file /absolute/path/to/report.pdf

Outside an active turn (or when scripting), use the repo CLI:

telegram send --file /absolute/path/to/report.pdf
telegram send --chat 123456789 --image /absolute/path/to/image.png
telegram send --instance bot2 --chat 123456789 --image /absolute/path/to/image.png

Delivery is explicit by design - generate the file, call the send command, rely on the receipt. The bridge dropped the older manifest/contract/count-repair state machine; what's there now is small, predictable, and observable.

Voice input

Send a voice message in Telegram and the bridge transcribes it locally before forwarding to the engine. No cloud ASR service. The default integration is Qwen3-ASR (or any local model wrapped in the same simple HTTP interface):

For a different ASR engine, override transcribeVoice() in src/telegram/delivery.ts - input is the path to an .ogg, output is the transcript string.

Session resume - the killer feature

Started a task locally with Claude Code? Continue it on Telegram, no copy-paste, no re-explaining. Codex users can attach an existing thread by ID and keep going.

/resume          ← lists recent local Claude sessions from the past hour
/resume 1        ← bot symlinks the session, switches workspace, binds session ID

This is the feature that makes the bridge feel like a real product instead of a demo. You don't have to start your work in Telegram to finish it there.

Budget control

Per-instance spending cap. When total cost hits the limit, new requests are blocked until the budget is raised or cleared.

npm run dev -- telegram budget show --instance work
npm run dev -- telegram budget set 10 --instance work
npm run dev -- telegram budget clear --instance work

The bot replies with a bilingual notice when the limit hits. Claude reports exact USD; Codex reports tokens only (cost shows as "unknown").

Observability and ops

Structured timeline events land in timeline.log.jsonl / audit.log.jsonl. Live-editing partial model output into the chat is no longer the default - typing indicators plus structured logs are. Inspect with:

npm run dev -- telegram timeline --instance work
npm run dev -- telegram dashboard --instance work
npm run dev -- telegram service status --instance work

There's also a service doctor and a dashboard included in the repo.

When to reach for it

• You want to drive Codex or Claude Code from your phone using the actual CLI, not a parallel chat protocol.
• You need multiple specialized bots with isolated state - reviewer, helper, researcher.
• You want to start work locally and continue it on mobile, or vice versa.

When not to

• You're looking for a thin chat-only Telegram wrapper around an LLM. This isn't that - it's a CLI runtime with Telegram as the surface.
• Multi-user environments where you can't trust local processes. The YOLO-off approval token is workstation-scoped.
• Air-gapped Telegram-less setups - obviously.

Built in TypeScript, requires Node.js 20+, runs on Windows, macOS, and Linux. Active development - the README's "what changed recently" section is informative; check it before pinning a version.