cc-telegram-bridge

Start Here

cc-telegram-bridge is not another hosted agent UI. It runs the real Codex, Claude Code, and Antigravity CLIs on your machine, then gives them a durable Telegram interface: access control, file delivery, voice transcription, scheduled tasks, session resume, multi-bot routing, and auditable long-running work.

The easiest setup path is to clone this repo, open it in Codex, Claude Code, or Antigravity, and tell the agent: "read the README and configure a Telegram bot for me". The bridge is designed to be installed and operated by the same CLI agents it exposes.

npm install
npm run build
npm run dev -- telegram configure <telegram-bot-token>
npm run dev -- telegram yolo on
npm run dev -- telegram service start

Then send a message to the bot, run the pairing command it gives you, and continue from Telegram. See Quick Start for the full walkthrough.

Recommended runtime: enable YOLO mode for hands-free Telegram instances you control: telegram yolo on --instance <name>. With YOLO off, the bridge can ask for approval in Telegram instead: Claude approvals are per tool request; Codex approvals are per turn because codex exec does not support mid-turn approval callbacks. Use unsafe modes only on a trusted machine and workspace.

What It Gives You

| Capability | What it means in practice | |---|---| | Remote control for real CLIs | Put Codex, Claude Code, or Antigravity on Telegram without wrapping them in a fake chat backend. | | Session continuity | Resume local Claude sessions, attach Codex threads, and bind Antigravity conversations from your phone, then continue on desktop later. | | Multimodal Telegram I/O | Send files, images, generated artifacts, voice messages, and audio documents through one bridge protocol. | | Durable operations | Keep cron jobs, audit logs, timeline logs, usage tracking, access checks, and service restart tooling outside model memory. | | Source-traceable research | Use the optional Brave/Tavily MCP for web_search, web_extract, provider status, fallback notices, and source logs. | | Multi-agent coordination | Use Agent Bus for instance-to-instance delegation, Mini Bus for topic-to-topic workflows, and Board for durable Kanban tasks. | | Feishu/Lark channel | Reuse the same bridge runtime from Feishu/Lark via the official Lark Channel SDK, with direct final replies, stop buttons, approvals, file/media delivery tags, Docs comments, cron, Board, Mini Bus, and Agent Bus. |

Feishu / Lark Channel

Telegram remains the deepest-tested channel, but Feishu/Lark is no longer a thin demo path. It is a second entrypoint that reuses the same engine adapters, sessions, workspace, agent.md, approval model, file-delivery tags, scheduled jobs, Board, Mini Bus, Agent Bus, and timeline/dashboard machinery.

npm run build
node dist/src/index.js lark wizard   # scan to create/bind a PersonalAgent app
node dist/src/index.js lark provision # re-check/provision an existing app
node dist/src/index.js lark permissions # print copyable tenant scope JSON
node dist/src/index.js lark permissions --missing # print only currently missing tenant scopes
node dist/src/index.js lark status
node dist/src/index.js lark doctor
node dist/src/index.js lark service start
node dist/src/index.js lark service logs 80
node dist/src/index.js lark service restart
node dist/src/index.js lark send --chat oc_xxx --message "hello from CLI"
node dist/src/index.js lark send --chat oc_xxx --reply-to om_xxx --thread --stdin
node dist/src/index.js lark timeline 20
node dist/src/index.js lark audit 20
node dist/src/index.js lark dashboard
node dist/src/index.js lark instructions path
node dist/src/index.js lark instructions set ./lark-agent.md
node dist/src/index.js lark engine claude
node dist/src/index.js lark yolo on
node dist/src/index.js lark budget set 12.50
node dist/src/index.js lark locale zh
node dist/src/index.js lark verbosity 2
node dist/src/index.js lark usage
node dist/src/index.js lark session list
node dist/src/index.js lark task list
node dist/src/index.js lark backup --out ./lark-state.cctb.gz

lark wizard uses the official Lark SDK PersonalAgent registration flow, prints a QR code, writes credentials to ~/.cctb/lark/lark.env (or CCTB_LARK_STATE_DIR/lark.env), then checks the app for the bridge surface: message receive events, card callbacks, bot message/resource scopes, Feishu Docs scopes, cloud-doc comment read/write scopes, and the group-all message scope required for /group all. If the app has management permission, the wizard patches event/callback subscriptions; otherwise it reports the exact management scope needed. The PersonalAgent QR template does not currently guarantee im:message.group_msg; if you want ordinary non-mention group messages through /group all, add or bulk-import that scope in the Feishu/Lark app permissions UI and rerun lark provision. Environment variables still win if you prefer manual credentials:

export LARK_APP_ID="cli_xxx"
export LARK_APP_SECRET="..."

Optional environment:

| Variable | Meaning | |---|---| | CCTB_LARK_STATE_DIR | State/workspace directory for the Lark service. Defaults to ~/.cctb/lark. | | CODEX_TELEGRAM_INSTANCE | Instance name used by the shared engine config. Defaults to lark. | | LARK_DOMAIN | Override Lark/Feishu API domain when needed. | | LARK_REQUIRE_MENTION_IN_GROUP | Defaults to true; group messages must mention the bot unless the specific chat is switched with /group all. | | CCTB_LARK_DOC_CREATE_AS / LARK_DOC_CREATE_AS | Optional user/bot override for lark.doc.create; default is bot. |

The Lark channel currently supports:

• inbound p2p/group messages normalized into the same Bridge.handleAuthorizedMessage path, protected by the same pairing/allowlist access store as Telegram;
• basic chat commands: /help, /status, /usage, /model, /effort, /fast, /engine, /yolo, /goal, /btw, /ask, /reset, /detach, Claude/Antigravity /resume scan and explicit /resume thread ... / /resume conversation ..., /cron, /group status|allow|deny|on|off|all|at, /board, /mini, /fan, /chain, /verify, /continue, and /stop;
• topic/thread isolation through conversationKey, plus replied-message context enrichment so short follow-ups like "继续" or "就这个" keep the quoted Lark message text;
• ordinary tasks return the final answer directly; interactive cards are reserved for stop controls, approvals, lark.choice / card choices, and archive continuation;
• approval cards for engine permission requests, with callback operators checked against bridge access policy before resolving;
• inbound image/file resources downloaded into the bridge workspace for the current turn, then cleaned up after staging/transcription; inbound Lark audio/video resources use the same local ASR path as Telegram before engine execution;
• outbound [send-file:/abs/path], [send-image:/abs/path], send.audio, send.video, send.batch, and whole-response fenced file:name.ext blocks delivered back to Lark;
• rich Feishu posts through lark.post tool tags when plain Markdown is too limiting;
• bridge-managed user choice cards through lark.choice, plus custom interactive cards through lark.card; button clicks are access-checked, audited, and fed back into the same bridge session;
• Feishu Docs creation through lark.doc.create for long specs and reviewable documents; the default creator identity is the app/bot, with opt-in as:"user" when you really want the local lark-cli user identity;
• Feishu Docs comment mentions: when a cloud-doc comment @mentions the bot, the bridge fetches comment context, runs the same engine, replies in-thread, and can execute lark.doc.create; chat-only delivery/reminder tools are reported as unsupported instead of being silently swallowed;
• Lark-delivered scheduled reminders/tasks through /cron or cron.add tool tags, with raw Lark chat/thread routing stored on each job so scheduler fires can return t