CLI WeChat Bridge
Drive local Codex, Claude Code, OpenCode and Pi sessions from WeChat, WeCom or Telegram while keeping the native terminal.
- Source repo
- UNLINEARITY/CLI-WeChat-Bridge
- Stars
- ★ 538
- Last updated
- 1d ago
- License
- AGPL-3.0
- Primary language
- TypeScript
- FA score
- 58/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude CodeChatGPT (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer running Codex or Claude Code in a local terminal who wants to keep sending tasks to the same session from WeChat while away from the desk.
- Not a fit if
- Teams that want to leave the local terminal behind and work only in a chat window
- macOS users who want zero native compilation and will not deal with node-pty build issues
- Users who need ChatGPT.app's bundled private executable, which the bridge will not call
- Source review
- 58/100 · Major gaps
What does this agent do, and when should you use it?
CLI WeChat Bridge is a Node.js (>= 22.13.0) command-line tool that bridges WeChat, WeCom and Telegram messages to locally running Codex, Claude Code, OpenCode and Pi, then syncs local output, approval requests and run status back to the chat channel. It ships setup commands (wechat-setup, wecom-setup, telegram-setup), direct launchers such as wechat-codex and telegram-claude, and resident daemons (wechat-daemon, wecom-daemon, telegram-daemon) that manage multiple CLI slots. The design keeps the local terminal the primary workspace: you still run the native CLI with your own flags, and the chat app is only a remote entry point. State stays session-centric locally, with multi-session bridging, /codex, /claude, /opencode and /pi switching, /confirm approvals, file transfer, and Codex 0.162+ --attach-current-session adoption of a running session. It is dual-licensed under AGPL-3.0-or-later plus a commercial option, and is distributed on npm as cli-wechat-bridge.
The bridge reads messages from WeChat, WeCom or Telegram and forwards them to a local Codex (WebSocket RPC), Claude Code (PTY interaction through node-pty), OpenCode (@opencode-ai/sdk session API) or Pi (native TUI extension), then routes CLI output, approval prompts and status back to the originating channel. wechat-setup performs QR login; wecom-setup opens a long connection via @wecom/aibot-node-sdk and takes Bot ID plus Secret; telegram-setup uses Bot API long polling with a Bot Token, and the latter two require sending /pair <code> in chat to pair the operator. In daemon mode, /codex, /claude, /opencode and /pi switch the active CLI, /all fans one prompt out to every started CLI, /status reports state, /model, /plan, /stop, /reset, /new and /resume control the session, /confirm, /deny and /answer handle approvals and structured questions, and /lang toggles Chinese or English. Files move both ways: inbound chat images and files are saved locally and their paths appended to the prompt, local files can be sent back, and Telegram attachments land in ~/.cli-bridge/telegram/inbound-attachments/. Each daemon also exposes a token-authenticated local IPC endpoint so scripts or web panels can inject text under exactly the same rules as chat messages.
- A developer running Codex or Claude Code in a local terminal who wants to keep sending tasks to the same session from WeChat while away from the desk.
- A team that needs an enterprise-sanctioned channel and uses a WeCom smart bot over WebSocket, with no public callback URL required.
- A Telegram user who creates a bot with @BotFather and drives a local project via telegram-codex.
- Someone working with several CLIs who switches between Codex, Claude Code and OpenCode by sending /codex, /claude or /opencode inside one daemon-bound working directory.
- A builder with a custom web panel or script who uses the daemon's local IPC endpoint to inject text into a CLI with the same semantics as chat.
- A Pi user who lets WeChat, WeCom or Telegram take over the same Pi session through the native TUI extension.
How do you install or deploy this agent?
Prerequisites: Node.js >= 22.13.0, at least one of Codex, Claude Code, OpenCode or Pi installed in PATH, and one remote channel (WeChat, WeCom or Telegram) ready.
Install globally from npm:
npm install -g cli-wechat-bridge@latestOn Linux you need native build tooling, and recent npm blocks install scripts, so allow them explicitly:
sudo apt install build-essential python3
npm uninstall -g cli-wechat-bridge
npm install -g cli-wechat-bridge@latest --allow-scripts=cli-wechat-bridge,node-ptyOn macOS, run xcode-select --install if compilation fails. On Windows, use Windows 10 1809 or newer, run npm rebuild node-pty if node-pty fails to load, and install the Visual C++ Redistributable. The older package name @unlinearity/cli-wechat-bridge still receives releases for existing users. After installing, wechat-daemon --doctor checks the environment.
How do you use this agent?
Log in or pair the channel you intend to use. WeChat QR login:
wechat-setupFor WeCom, create an API-mode smart bot in the WeCom client (Workbench → Smart Robot) with long-connection mode, then enter its Bot ID and Secret:
wecom-setupFor Telegram, create a bot with @BotFather using /newbot, then enter the token and send /pair <six-digit code> in the bot's private chat within 10 minutes:
telegram-setup
telegram-setup --checkChange into your project directory and launch the CLI you want directly:
cd D:\work\your-project
wechat-codex
wecom-claude
telegram-opencodeFor long-running use with switchable CLIs, start a daemon instead:
wechat-daemon --adapter codex
wecom-daemon --adapter claude --profile work
telegram-daemon --adapter codexTo attach a running Codex session (needs Codex >= 0.162, opens no visible CLI):
telegram-codex --attach-current-session
telegram-codex --attach-current-session --codex-thread-id <id>Then send plain text from WeChat, WeCom or Telegram to submit work. Under a daemon you can also use /codex, /claude, /opencode and /pi to switch, /status to inspect, /confirm or /deny to answer approvals, and /daemon-stop to stop. Send one message from WeChat first after startup so the bridge captures a fresh context_token.
What are this agent's strengths and limitations?
- Keeps the local CLI as the primary workspace with native terminal behavior and advanced launch flags; the chat app is only a remote entry point.
- One daemon can switch between Codex, Claude Code, OpenCode and Pi remotely via /codex, /claude, /opencode and /pi, opening or reusing the visible terminal automatically.
- Approvals and structured input work remotely: /confirm and /deny handle requests one at a time, and /answer supports single and multi-question replies like /answer 1=Yes;2=2.
- Bidirectional file transfer: inbound images and files are saved locally and their paths appended to the prompt, with Telegram also accepting video, voice and audio.
- Each daemon exposes a token-authenticated local IPC endpoint so scripts or web panels can inject text under the same rules as chat.
- The Claude Code adapter relies on node-pty PTY interaction; without node-pty it falls back to a compatibility mode where Claude Code may not bridge correctly.
- A daemon is bound to its start-up working directory, and switching directories from the remote channel is not supported.
- It only invokes standalone CLIs available in PATH, and will not discover or call private executables bundled inside apps such as ChatGPT.app.
- Version gates stack up: Codex --attach-current-session needs Codex >= 0.162, and Pi 0.85.0+ requires Node.js >= 22.19.0.
- After a cold start or long idle, sending from the local terminal first can fail on WeChat because the context_token has expired; you must send a message from WeChat first.
How does this agent compare with similar options?
The README names earlier reference work: openclaw-weixin (an early WeChat / Claude Code Channel project) and the @tencent-weixin/openclaw-weixin npm package from the Tencent WeChat team. Unlike those single-channel references, this project covers Codex, Claude Code, OpenCode and Pi together and unifies three remote entry points — WeChat, WeCom and Telegram.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| CLI WeChat Bridge This agent | 58 · Major gaps | CLIFree + model costs | ★ 538 | 1d ago | TypeScript | Codex · Claude Code |
| Alethe — Multi-Agent Coding Workspace | 65 · Some gaps | Desktop appFree + model costs | ★ 927 | 1d ago | TypeScript | Codex · Claude Code |
| Plannotator | 78 · Good | CLIFreemium | ★ 9.5k | today | TypeScript | Codex · Claude Code |
| NeuroSquad Terminal Dashboard | 76 · Good | CLIFree + model costs | ★ 53 | 5d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: README states Pi runs as a full-permission local agent with --approve and no added tool-approval layer; Claude startup settings inject a WebFetch(domain:*) allow rule (disable via CLI_BRIDGE_STRICT_APPROVAL=1); --yolo / --dangerously-skip-permissions are passed through to the underlying CLI. Approval queues are well tested (approval-queues.test.ts covers one-at-a-time promotion, retention on write failure, child-session ownership), so user_confirmation scores 2. least_privilege scores only 1: default network allowlisting, no approval layer for Pi, and a token-authenticated local daemon IPC that can send messages on the channel widen the permission surface with no least-privilege rationale. data_flow_transparency and sensitive_data_handling score 1 each: README names credential paths (~/.cli-bridge/telegram/account.json) but does not systematically describe where message content, attachments, and context tokens flow, how long they are retained, or whether logs are redacted. dependency_security scores 2: package.json pins transitive dependencies via overrides (hono, qs, path-to-regexp, etc.) and CI installs with --frozen-lockfile, which is positive; no audit report or vulnerability-handling record is provided. external_effects and rollback score 1 each: the daemon auto-takes-over and cleans stale bridge processes, locks, and endpoints, which is a real side effect, while recovery relies on /daemon-stop and reinstall with no documented rollback procedure. source_attribution scores 2: source files carry SPDX headers with copyright and origin, and README lists key dependencies and reference projects, but third-party code provenance is not itemized.
self_consistency scores 2: README command/parameter tables align with the 21 bin entries in package.json, and test files map to source paths. dependency_availability scores only 1: node-pty is a native module requiring a compiler toolchain and npm allow-scripts approval, and README concedes the Claude adapter may not bridge correctly without PTY; the project also depends on specific external CLI version ranges, a drift risk asserted rather than mechanically enforced. failure_messages scores 2: tests assert concrete failure strings ('Send /model again', 'outside the displayed range', 'another session', 'expired', 'Restart'), and README describes context_token expiry and hook-timeout behavior; there is no unified error-code or severity scheme.
audience_and_scenarios scores 2: README clearly targets developers who keep a local terminal workflow and want a remote entry point, and states it does not turn chat into the primary interface. capability_boundaries scores 2: per-adapter status and limits are listed (Pi has no remote approval, Claude needs an idle native prompt, OpenCode requires server read-back, Codex attach needs 0.162+). trigger_precision scores 2: the command table distinguishes daemon vs direct-start scope, emoji bindings must lead the message, and /model lists expire after 5 minutes; emoji-vs-plain-text boundaries can still misfire. environment_fit scores 2: Windows/macOS/Linux and Node >=22.13.0 are covered with a three-OS CI matrix, but Pi needs Node >=22.19.0 and Windows needs 1809+, so constraints are non-trivial.
information_architecture scores 3: README has a documentation index, sectioned command tables, parameter tables, and an adapter matrix. install_notes scores 3: install/update, node-pty build prerequisites, allow-scripts syntax, per-platform requirements, and --doctor self-check all come with concrete commands. naming_stability scores 2: README documents removal of wechat-*-start aliases and wechat-bridge* commands in 1.1.5 and continued dual publishing of the old scoped package, which is a recorded migration, but naming has churned. examples_and_faq scores 2: screenshots and command examples exist with a troubleshooting link, but no FAQ body is in the provided evidence. known_limitations scores 2: README lists no remote cwd switching, no automatic OCR/PDF extraction, Pi full permissions, and required restarts after upgrade. license scores 3: LICENSE.txt is the full AGPL-3.0 text, package.json declares AGPL-3.0-or-later, and README explains dual licensing and commercial terms. versioning_changelog scores only 1: package.json is at 1.2.3 and README points to docs/releases/README.md, but no changelog content is in the evidence. maintenance_responsibility scores only 1: an author and contact (GitHub @UNLINEARITY) are visible, but the publisher is unverified by the FollowAgents registry and there is no maintenance commitment, response target, or security-disclosure channel.
output_usability scores 2: remote output is tagged ([codex]/[claude]/...), with /status, /model, /resume, and file return, and long messages are split per channel limits; output remains largely terminal text with limited structure. marginal_value scores 2: bridging local CLI sessions to WeChat/WeCom/Telegram while preserving the native terminal experience is a real increment for a specific workflow, though comparable bridges exist and differentiation rests on multi-adapter support and approval sync. cost_benefit scores only 1: it needs a resident daemon, native-module compilation, external CLI version alignment, and credential management, so operating cost is non-trivial while the benefit is concentrated in remote access when away from the machine.
claim_traceability scores 2: most README claims map to package.json bin/scripts and to test filenames (adapter-control, approval-queues, claude-resume), but no per-claim implementation pointers are given. cross_source_corroboration scores 2: README, package.json, CI workflows, and tests corroborate each other on command entries, quality gates, and platform matrix; whether CI actually blocks merges depends on branch protection, which README does not confirm. fact_inference_separation scores 2: README distinguishes verified version ranges from experimental features (Codex attach marked experimental), but some capability descriptions (per-adapter sync semantics) lack checkable boundaries. This is a static source review; nothing was executed, so confidence is low.
- The Pi adapter runs as a full-permission local agent with --approve and no per-tool approval layer; remote messages can trigger local file writes and command execution, so use it only in controlled directories with trusted operators.
- The Claude adapter injects a WebFetch(domain:*) allow rule by default; set CLI_BRIDGE_STRICT_APPROVAL=1 explicitly if you want strict approval, otherwise routine network fetches pass through.
- The daemon exposes a token-authenticated local IPC that lets external programs dispatch text or send channel messages; verify the exposure scope of that endpoint and how the token is stored.
- README does not systematically describe the flow, retention, or log redaction of message content, attachments, and context tokens; credentials live under ~/.cli-bridge, so assess data sensitivity yourself.
- Daemon startup auto-takes-over and cleans stale bridge processes, locks, and endpoints, which is a side-effecting automatic behavior with limited rollback; validate in a non-critical environment first.
- It depends on the node-pty native module and specific external CLI version ranges; installation needs a compiler toolchain and npm allow-scripts approval, and upgrades require restarting the bridge/daemon/visible CLI.
- The publisher is unverified by the FollowAgents registry, and this evidence set contains no changelog body or security-disclosure channel; verify version and provenance before production use.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
版本 1.2.3 发布日期： 2026 年 10 月 13 日 概述 1.2.3 新增第三个消息信道 Telegram，并支持将消息信道附加到已经运行的 Codex TUI 会话。本版本修复独立 bridge 与 attach 模式下 Telegram 最终回复无法回传的问题，使启动提示显示实际信道，并提供完整中英文 README 与语言切换导航。 新功能 Telegram Bot API 信道 Telegram 沿用微信、企业微信的直接启动和 daemon 工作流，支持 Codex、Claude Code、OpenCode 与 Pi。信道使用官方 Bot API 长轮询，不需要公网回调地址。 1. 在 @BotFather 中发送 /newbot 创建机器人并取得 Bot Token。 2. 在本地运行 telegram-setup，输入 token。 3. 打开机器人的私聊，点击 Start，在 10 分钟内发送终端显示的 /pair <code>。 4. 进入项目目录，运行 telegram-daemon --adapter codex，或使用对应的直接启动命令。 | 用途 | 命令 | | --- | --- | | 操作者配对 | telegram-setup | …View on GitHub ↗ -
Release notes excerpt
版本 1.2.2 发布日期： 2026 年 10 月 12 日 概述 1.2.2 进一步完善微信、企业微信与本地 CLI 之间的交互：新增 /lang 实时语言切换，支持远程回答 Claude Code 的结构化问题，并将审批统一为逐项处理。本版本同时修复 OpenCode 和 Codex 的子代理事件干扰父任务、OpenCode 2 表单答案提交错误，以及 Pi 错误信息丢失和中断状态不准确等问题。 新功能 通过 /lang 切换提示语言 微信和企业微信的直接启动模式与 daemon 模式均支持以下指令；本地测试通道沿用相同的命令规则： | 指令 | 功能 | | --- | --- | | /lang | 查看当前语言及切换方式 | | /lang zh | 切换为中文 | | /lang en | 切换为英文 | - /language 是 /lang 的别名；语言参数也接受 chinese、english、中文 和 英文。无效参数会返回使用说明，不会作为 prompt 发送给模型。 …View on GitHub ↗ -
Release notes excerpt
版本 1.2.1 发布日期： 2026 年 9 月 28 日 概述 版本 1.2.1 在保留 OpenCode 1.18 支持的同时接入 OpenCode 2，让微信路由与可见 Codex 会话保持一致，并完成 Claude Code 切换模型时的二次确认。同时将 Codex CLI 已验证范围扩展至 0.157，并恢复已安装命令入口的可执行权限。 支持 OpenCode 2 bridge 现在同时支持 OpenCode 2 与 1.18。wechat-opencode、wecom-opencode 和 daemon 管理的 OpenCode 会根据已安装的 CLI 版本选用相应连接。可见终端会话、远程模型与计划模式控制、审批与提问、会话恢复、最终回复，以及在本地 TUI 中提交的提示词继续与远程通道连接。OpenCode 2 会转发已提交的本地提示词；其 TUI 不再发布草稿更新事件，因此输入中的草稿不会同步。每周 CLI 兼容性检查分别覆盖两条受支持的版本线。 可见会话与模型切换 …View on GitHub ↗