CLI-WeChat-Bridge: Putting a WeChat Door on a Local Agent Terminal

The gap it fills: agent sessions that live on one machine

A local coding agent is tied to the machine it runs on. You start Codex or Claude Code in a project directory, work through a task, and when you walk away the session is stranded. The README frames the target user narrowly: people whose main workflow is still the local terminal, who want to keep using the native CLIs and their advanced launch flags rather than moving to a web interface or a hosted bot, and who want to send requests from WeChat or WeCom while away and receive output and status back. The project is explicit that it does not try to turn WeChat into the primary work surface. The local CLI stays primary; the chat channel is a remote entry point; thread state and approval flow remain centred on the local session. That positioning matters because it rules out a whole class of expectations. This is not a way to give a team a shared agent. It is a way to reach your own session from your phone.

Two channels, four adapters, and where the terminal is faked

The bridge supports personal WeChat and WeCom (企业微信) as remote channels and four local CLIs as back ends: Codex, Claude Code, OpenCode and Pi. Each pairing gets its own entry command, so there are eight direct commands in total: wechat-codex, wecom-codex, wechat-claude, wecom-claude, wechat-opencode, wecom-opencode, wechat-pi and wecom-pi. The adapters do not all talk to their CLI the same way, and the README is unusually candid about this. Claude Code currently works through PTY interactive mode, meaning it depends on node-pty for full terminal emulation; without node-pty it falls back to a compatibility mode in which, per the documentation, Claude Code may not bridge correctly. Codex communicates mainly over WebSocket RPC and 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 needs no terminal emulation either. The architecture document linked from the README is where the PTY and RPC dependency analysis lives, and it is the right place to look before assuming all four adapters behave alike.

Installing it, and the node-pty trap on Linux and Windows

The package is published on npm and installed globally. The README gives npm install -g cli-wechat-bridge@latest as the standard command, and notes that the older scoped name @unlinearity/cli-wechat-bridge continues to be published in parallel, so existing users of the scoped package can upgrade normally. Node.js 22.13.0 or newer is required. The friction is in the native module. Recent npm versions on Linux block install scripts by default, and the README supplies a specific recovery sequence: uninstall, then reinstall with --allow-scripts=cli-wechat-bridge,node-pty, keeping the package name on the same command line. It warns that running npm install -g --allow-scripts=... without a package name makes npm read the current directory's package.json and can fail with ENOENT. To make later global upgrades keep allowing those two scripts, the README suggests npm config set allow-scripts=cli-wechat-bridge,node-pty --location=user. Linux users typically need build-essential and python3, or the distro equivalents (dnf groupinstall "Development Tools", apk add build-base python3). macOS users may need xcode-select --install. Windows needs build 18309 or later, and if node-pty fails to load, npm rebuild node-pty. wechat-daemon --doctor checks the environment.

Login, pairing, and the context_token ordering rule

Personal WeChat login runs through wechat-setup, which fetches a QR code, prints it in the terminal, waits for you to scan and confirm in WeChat, then stores local credentials. The QR defaults to small mode; on Windows terminals where the small rendering breaks, wechat-setup --qr-mode normal switches it. After a successful login the program clears old sync cursors and context tokens, which the README describes as preventing stale session state from contaminating the new login. WeCom takes a different path: it uses the official intelligent-bot long connection, so no public callback URL is needed. You create an API-mode bot in the WeCom client under 工作台 then 智能机器人, choose the long-connection option, obtain a Bot ID and Secret, run wecom-setup, and then send /pair <code> in a direct chat with the bot to complete one-time operator pairing. The operational rule worth internalising is in section four of the README: send a message from WeChat to the bot before relying on local-to-WeChat sync. That gives the bridge a fresh context_token. If you start from the local terminal after a cold start or a long idle period, the bridge will usually still capture the input and hand it to the CLI, but the reply may fail to reach WeChat because the old token has expired. The visible symptom is a local answer that WeChat never sees, and the documented fix is to send one message from WeChat, after which two-way sync resumes.

Single-workspace mode versus the daemon

Without a daemon, the four direct commands behave as a single active workspace switcher. Only one project talks to WeChat or WeCom at a time. Running the command in a different directory explicitly switches the active workspace. If the bridge detects that the visible side is still running but the worker state is abnormal, for example stopped or error, it restarts the bridge and reopens the visible side automatically. That is a reasonable recovery behaviour for a single-session tool, but it also means you cannot keep two projects live simultaneously in this mode. The daemon is the answer to that. Starting wechat-daemon in a project directory keeps the remote channel online for long periods and lets you switch between Codex, Claude Code, OpenCode and Pi. WeCom uses the same workflow, with wecom-daemon --adapter claude selecting the adapter explicitly. The README states that after starting the daemon you send a command in the remote channel to choose the active terminal, though the excerpt provided cuts off before listing those commands. If multi-CLI switching is the reason you are interested, verify the exact command names in the current documentation rather than guessing.

What the bridge does not do, and what breaks first

The clearest limitation is the PTY dependency for Claude Code. If node-pty will not build on your machine, the documented fallback may leave Claude Code unable to bridge, while Codex, OpenCode and Pi continue to work. On a locked-down Linux host without a compiler toolchain, that effectively removes one of the four supported CLIs. The context_token behaviour is the second failure mode, and it is a real one: a cold start followed by local-first input can produce a reply that never arrives in WeChat, with no obvious error at the terminal. Treating "send a WeChat message first" as a required step after any restart avoids most of it. A third constraint is structural rather than a bug. Because the local session is the centre of the design, the direct commands allow only one active workspace, so anyone expecting several concurrent agent sessions reachable from one chat account will be disappointed until they move to the daemon. Finally, the README notes that the CLIs should be kept reasonably current and pins OpenCode to >= 1.18.0 < 2.0.0, which means an OpenCode major upgrade can break the adapter until the bridge catches up. Pi is documented as verified at 0.84.2 and requires a working pi executable on the machine.

How this differs from a hosted bot framework

The obvious alternative is a hosted bot platform such as a WeCom or WeChat bot service that runs the agent on the provider's infrastructure and exposes it through a web dashboard. The difference in approach is where the session and its state live. A hosted bot owns the conversation, the model credentials and the execution environment; you reach it through an API or a web UI, and your local files are not part of the picture unless you upload them. CLI-WeChat-Bridge inverts that. The agent process runs on your machine, in your project directory, under the CLI you already configured, and the chat channel is only a transport for input, output, approval prompts and status. The README also mentions file transfer in both directions, local files to WeChat and WeChat files to the terminal, which only makes sense when the terminal is the real workspace. The trade-off is operational: you carry the Node.js runtime, the native module build, the QR login and the token refresh behaviour, and you get no shared team access. In exchange, nothing about your agent setup has to move.

Maintenance, release cadence and the AGPL-3.0 question

The release history shows frequent small versions: 1.1.5, 1.1.6 and 1.1.7 within roughly two weeks in August and September 2026, with the repository last pushed in September 2026. That cadence suggests active maintenance, and the README maintains a releases directory with per-version change notes, which is where you should look before upgrading rather than assuming patch releases are inert. The upgrade path itself is npm install -g cli-wechat-bridge@latest, with the --allow-scripts caveat on Linux if npm blocks install scripts again. The licence is AGPL-3.0, and that is a decision point, not a footnote. AGPL-3.0 carries network-use obligations that differ from permissive licences, so if you plan to expose a modified version of this bridge as a service to others, the terms matter. I am not in a position to give legal advice, and the specifics depend on how you deploy it; if that scenario applies to you, have someone qualified read the licence against your architecture. For personal or internal use on your own machine, the practical question is smaller, but it should still be answered before the tool becomes load-bearing.

Editorial conclusion

Adopt it if your agent work already lives in a local CLI, you are willing to run Node.js 22.13.0 or newer, and you accept AGPL-3.0 terms for whatever you connect to it. Do not adopt it if you need a hosted multi-tenant bot, if you cannot install native build tooling for node-pty, or if you intend to ship a closed derivative. Before installing, run wechat-daemon --doctor on the target machine, confirm your CLI versions match the supported ranges (OpenCode >= 1.18.0 < 2.0.0, Pi verified at 0.84.2), and send one message from WeChat first so the bridge caches a fresh context_token.

Official sources

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