CLI WeChat Bridge: run Codex, Claude Code, OpenCode or Pi from WeChat

The problem CLI WeChat Bridge solves, and for whom

Most chat-to-agent bridges invert the relationship: the chat app becomes the interface and the agent runs somewhere else. CLI WeChat Bridge does the opposite. The README states the positioning plainly: the local CLI stays the primary workspace, WeChat or WeCom is a remote entry point, and session consistency, thread state and approval flow remain centered on the local session.

The intended user is someone whose main workflow never left the terminal. You keep launching Codex, Claude Code, OpenCode or Pi with your own flags and your own project directory, and the bridge adds a second door into that same session. The README lists the matching scenario: you want to keep using the native CLI rather than migrating to a web page or a hosted bot, and you want to send requests from WeChat after leaving the desk and receive output and status updates back.

That framing also defines who is out of scope. If you have no local CLI installed, or you want the chat platform to be the work surface, this project is not aimed at you. It is a remote control for a session that already exists on your machine.

How the bridge attaches to each CLI: PTY, RPC, and direct terminal inheritance

The adapters do not share one transport. According to the README and the architecture document it links to, each CLI is bridged differently, and that difference has practical consequences.

Claude Code is driven through a PTY interaction mode, which is why node-pty matters. The README warns that when node-pty is unavailable the adapter falls back to a compatibility mode, and Claude Code may not bridge correctly in that mode. Codex talks mainly over WebSocket RPC, so it is usually unaffected by a missing node-pty. OpenCode does not depend on node-pty at all. Pi inherits the real terminal of a visible companion process, so it also does not need PTY emulation.

Around those adapters sits the session layer. The README describes thread and session sharing between WeChat and the local terminal, two-way conversation, sending local files to WeChat, and receiving files from WeChat back into the terminal. It also mentions binding WeChat emoticons to commands and a two-way /resume for restoring a conversation. Version 1.1.7 added multi-CLI switching, which is what makes a single daemon able to hand the remote channel between Codex, Claude Code, OpenCode and Pi.

Installing CLI WeChat Bridge and running a first session

Prerequisites come first. Node.js must be 22.13.0 or newer, and at least one supported local CLI must already be installed and current. The README pins OpenCode to >= 1.18.0 < 2.0.0 and notes Pi was verified at 0.84.2 with a working pi executable on the machine.

The package installs globally from npm:

npm install -g cli-wechat-bridge@latest

On newer npm releases for Linux, install scripts are blocked by default. The README gives a clean reinstall that names both packages, and stresses that the package name must appear in the same command:

npm uninstall -g cli-wechat-bridge
npm install -g cli-wechat-bridge@latest --allow-scripts=cli-wechat-bridge,node-pty

To keep later global upgrades working, the README suggests writing a user-level npm config:

npm config set allow-scripts=cli-wechat-bridge,node-pty --location=user

Linux users need build tools for the native module, for example on Debian or Ubuntu:

sudo apt install build-essential python3

After install, check the environment before logging in:

wechat-daemon --doctor

Then complete the channel login. Personal WeChat uses the setup command, which prints a QR code in the terminal and waits for you to scan and confirm:

wechat-setup

WeCom takes a different route. You create an API-mode bot in the WeCom client under Workbench, Intelligent Robot, choosing the long-connection option, and obtain a Bot ID and Secret. Then:

wecom-setup

The README says a one-time operator pairing is completed by sending /pair <code> to the bot in a direct chat. Finally, enter your project directory and start the entry point for your CLI:

cd D:\work\your-project
wechat-codex

The equivalent commands are wechat-claude, wechat-opencode and wechat-pi for WeChat, and wecom-codex, wecom-claude, wecom-opencode and wecom-pi for WeCom. Without a daemon, these behave as a single active workspace switcher: one project talks to the channel at a time, and running the command from another directory explicitly switches the active workspace.

Send from WeChat first, or the reply may never arrive

This is the failure mode the README spends the most words on, and it is easy to misread as a bug. After starting the bridge, send one message from WeChat to the bot first, whether that is hello or an actual task. The bridge needs a fresh context_token from that inbound message before local terminal input, final replies and approval prompts can be reliably pushed back to WeChat.

If you cold start or leave the bridge idle and then type in the local terminal first, the README says the bridge will usually still capture the local input and hand it to the chosen CLI. The reply path is what breaks: the old context_token has expired, so the local side shows an answer while WeChat stays silent. Sending one message from WeChat restores two-way sync from that point on.

That ordering requirement is a real constraint on how you use the tool, not a footnote. It means the bridge is not symmetric at cold start, and any automation that assumes the terminal can initiate a conversation after a long idle period will hit this. The README does not document rollback behavior for a failed send, so treat the inbound-first habit as the supported path.

Where CLI WeChat Bridge is the wrong tool

The node-pty dependency is the first hard boundary. Because the Claude Code adapter works through PTY interaction, a machine where the native module will not compile puts that adapter on the compatibility path, and the README states Claude Code may not bridge correctly there. If Claude Code is your only CLI, verify node-pty before anything else. Windows needs 10 version 1809 (build 18309) or higher, and the README points to npm rebuild node-pty or a reinstall plus the Visual C++ Redistributable if loading fails.

The second boundary is scope. Only four CLIs are supported. A team standardized on something else gets nothing from this project.

The third is the single-workspace behavior of the direct commands. Without the daemon, one project talks to the channel at a time. If you expect several repositories to answer WeChat concurrently, the direct entry points are the wrong layer; the daemon is the documented way to keep the channel online and switch between CLIs. And if you want a shared, multi-user assistant that anyone in a company can query, this design is pointed the other way: the session belongs to your local machine and your local terminal.

How it differs from running an agent inside the chat platform

The obvious alternative is an agent that lives inside WeChat or WeCom itself, where the bot owns the conversation and the model runs on a server. The difference is not cosmetic. In that model the chat transcript is the session; here the local CLI session is the session, and WeChat is a view onto it. Anything that depends on your local files, your local environment variables, your installed CLI version and your project directory only exists in the second model.

A concrete consequence is approval flow. The README says approval requests and run status are synchronized back to the channel, which only makes sense because the CLI is still running locally and still asking for permission. A hosted bot has no equivalent local approval step to forward.

The trade-off runs the other way too. A chat-native agent works for anyone with the app, needs no Node.js, no build tools and no node-pty, and has no context_token ordering rule. CLI WeChat Bridge asks you to maintain a machine, a Node runtime and a working native module in exchange for keeping the terminal as the source of truth. Choose based on which of those two costs you would rather carry.

Maintenance, upgrades and the AGPL-3.0 licence

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent and small: 1.1.5 on 2026-08-25, 1.1.6 on 2026-08-31, and 1.1.7 on 2026-09-01. Upgrades go through the same npm command as installation, and the README notes the older package name @unlinearity/cli-wechat-bridge continues to be published in parallel, so existing installs of that name can upgrade normally while new users take the shorter cli-wechat-bridge.

The package ships bin/, dist/ and a small postinstall script for node-pty permissions. There is a wechat-check-update command and a wecom-check-update command in the bin map, so update checking is exposed as its own entry point rather than buried in the daemon.

The licence is AGPL-3.0-or-later, declared in package.json as AGPL-3.0-or-later and shown in the README badge as AGPL-3.0. That is a copyleft licence with a network clause. If you plan to run a modified version as a service that others interact with over a network, the licence terms are the thing to read, and this article is not legal advice. For personal or internal use where you are not distributing or offering a modified version as a network service, the practical constraint is smaller. The README does not document any commercial licensing option.

Editorial conclusion

Adopt it if your working directory is already a terminal running Codex, Claude Code, OpenCode or Pi, and you want a phone-side entry point without moving the session to a hosted bot. Do not adopt it if you need a public callback endpoint, a web UI, or a CLI outside the four listed ones. Before trusting it with real work, run wechat-daemon --doctor, confirm node-pty compiled on your platform, and send one message from WeChat first so the context token is fresh.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. UNLINEARITY/CLI-WeChat-Bridge on GitHub