# cli-wechat-bridge: two lockfiles, fourteen binaries and two of them undocumented, and the only adapter without a verified version is the one that silently degrades

> cli-wechat-bridge lets you drive Codex, Claude Code, OpenCode, or Pi from WeChat or WeCom while the local terminal stays the primary interface. Four adapters sit behind fourteen globally installed commands, plus a daemon that keeps the remote channel online and lets you switch between them. The engineering care is concentrated in the platform edges, and the gaps are concentrated in the packaging.

**UNLINEARITY/CLI-WeChat-Bridge** — 将 AI 命令行工具以最为原生的方式，集成到微信 ClawBot / 企业微信 bot 中，目前支持集成 Codex、Claude Code、OpenCode、Pi Agent。 支持微信和本地终端线程（thread/session）共享、双向对话，支持将本地文件传输至微信，微信也支持发送文件到终端。现已支持多 cli 切换、微信表情绑定指令、双向 /resume 对话恢复。

- Repository: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
- Website: https://unlinearity.github.io/CLI-WeChat-Bridge/
- Stars: 522 · Forks: 56
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/unlinearity-cli-wechat-bridge

## Two lockfiles sit in the root and the install path reads only one

The top level of the repository holds `bun.lock` and `package-lock.json` alongside `.npmignore`, three tsconfig files, `eslint.config.mjs`, `bin/`, `src/`, `test/`, `scripts/`, `docs/`, `site/`, and `assets/`. Two lockfiles means two package managers have each been authoritative here. The documented install is npm:

```bash
npm install -g cli-wechat-bridge@latest
```

which honours `package-lock.json` and ignores `bun.lock` entirely. The rest of the page is npm-shaped too, down to the `postinstall` script, the `--allow-scripts` flag, and a documented npm error. So the dependency graph you actually install is the npm one, and the bun lockfile is either stale or maintained for a contributor path the README never describes. There is no note explaining which lockfile to trust when they disagree, which is exactly the situation where a second lockfile does harm rather than good.

## Fourteen binaries ship and two never appear in the documentation

The `bin` map declares fourteen commands: `wechat-codex`, `wechat-claude`, `wechat-opencode`, `wechat-pi`, `wechat-daemon`, `wechat-setup`, `wechat-check-update`, and the same seven with a `wecom-` prefix. The documentation covers twelve of them across its setup and launch sections. The two it never mentions are `wechat-check-update` and `wecom-check-update`, which is an odd gap for a project whose page devotes a collapsible section to the npm update dance. The published tarball is narrower than the repository: `files` lists `bin/`, `dist/`, one script, the README, and the licence. That one script is `scripts/ensure-node-pty-permissions.mjs`, shipped because `postinstall` runs it and nothing else from `scripts/` is needed at install time. The `bin/` directory is listed wholesale rather than entry by entry, so all fourteen land on your PATH whether or not you use four of them.

## The adapter with no verified version is the one that degrades silently

Each adapter is verified against a different granularity of version. Codex is verified on `0.149.x` through `0.157.x`. OpenCode supports both `1.18.x` and `2.0.x`, a range that spans a major version. Pi is verified on exactly `0.85.1`. Claude Code has no version given at all. That omission lands on the adapter with the most fragile install path. node-pty provides full terminal emulation, the Claude Code adapter currently works through PTY interactive mode, and when node-pty is unavailable it falls back to a compatibility mode in which, as the page puts it, Claude Code may not bridge properly. The Codex adapter mostly speaks WebSocket RPC and is usually unaffected, OpenCode does not depend on node-pty at all, and Pi inherits a visible companion's real terminal. So the adapter with no stated tested range is also the only one whose behaviour changes without the install failing.

## The first message has to travel from WeChat or replies stop arriving

One step in the quick start is marked important and exists because of a directional asymmetry. The bridge can only reply into a WeChat conversation once it holds that conversation's `context_token`, and the token is refreshed by an inbound message from WeChat. So if you start cold or come back after a long idle period and send from the terminal first, the bridge will still capture your local input and hand it to whichever adapter is active, but the reply back to WeChat can fail because the token went stale. The symptom is described plainly: the local side has an answer and WeChat does not, and once you send one message from WeChat the two-way sync recovers. A fresh login also clears the old sync cursors and context tokens. That is a real design constraint rather than a bug, but it presents to the user as silent message loss in one direction.

## The metadata homepage is a GitHub anchor while a real project site exists

Three homepages exist for one project. The package metadata sets `homepage` to a GitHub URL with a `#readme` fragment, which npm renders as the project's link on the package page. A third address lives outside the package: a separate project site, and the README links it as a product page near the top, along with a documentation site and an announcement of the same repository also being hosted on AtomGit. The badge row is a similar story: five anchors, three of which point at the unscoped npm package, one at the scoped legacy name, and one that opens and closes with nothing inside it. The body text explains the dual naming, saying the old name `@unlinearity/cli-wechat-bridge` keeps publishing in sync and that new users should prefer the shorter `cli-wechat-bridge`. So the one place a package consumer is guaranteed to look is the one carrying a self-link instead of the documentation site.

## Three version schemes across four adapters and no shared floor

Beyond the adapter table there is one runtime floor for everything: Node.js `>= 22.13.0`, with a recommendation to install the current long term support release. There is no floor for the CLIs themselves, only the verified ranges, and those ranges are not floors so much as observations. `0.149.x` to `0.157.x` for Codex is a nine-minor window, and a Codex release past `0.157` is neither verified nor excluded. `1.18.x` and `2.0.x` for OpenCode says the adapter was built against two incompatible majors, which implies either two code paths or an untested assumption about the newer one. `0.85.1` for Pi is a single patch release, so any update to Pi is unverified. Windows gets its own floor too, build 1809 or 18309 or higher, which is an unusually specific requirement to be carrying without a stated reason.

## The remote channel can switch adapters and stop the daemon

Once the daemon is running, the remote channel is not a read-only view. Four slash commands select the active terminal, `/codex`, `/claude`, `/opencode`, and `/pi`, and each accepts an optional prompt that is forwarded immediately after the switch. A fifth, `/daemon-stop`, stops the daemon. Daemon mode also automatically takes over and cleans up old single-bridge processes, stale locks, and dead endpoints at startup, and it binds itself to the working directory it was launched in, with no way to change directories from the remote channel. The direct launch commands without a daemon behave as a single active workspace switcher instead: only one project talks to WeChat at a time, running in another directory switches the active workspace explicitly, and if a visible endpoint is still running with a bad state such as stopped or error the bridge restarts it. That is a lot of authority for a chat message, which is the point of the tool and also the thing to think about before binding it to an account.

## Conclusion

This is a well-engineered remote control surface for people whose agent session already lives in a local terminal, and it is explicit about its hard edges, which is rarer than it should be: which adapter needs a native module, which one falls back and what breaks in the fallback, and which direction the first message has to travel. Before you install it, send one message from WeChat first, because the reverse direction fails silently until a `context_token` is refreshed. Check that node-pty built, since the Claude Code adapter is the one that quietly drops into a mode the page warns may not bridge at all. And if you maintain it, the three cheap fixes are a second lockfile decision, two missing command references, and a version for Claude Code.

## FAQ

### Which CLI tools can cli-wechat-bridge drive?

Codex, Claude Code, OpenCode, and Pi. The bridge only calls standalone CLIs that are installed and executable on `PATH`, and explicitly will not find or call private executables bundled inside desktop applications such as ChatGPT.app.

### How do I install cli-wechat-bridge?

`npm install -g cli-wechat-bridge@latest`, which requires Node.js 22.13.0 or higher. Newer npm releases on Linux can block install scripts, in which case the page gives a clean reinstall with `--allow-scripts=cli-wechat-bridge,node-pty`, and the native build tools node-pty needs per platform.

### Why does cli-wechat-bridge need a message sent from WeChat first?

The bridge can only reply into a WeChat conversation once it holds that conversation's `context_token`, and the token is refreshed by an inbound message. Sending from the terminal first still reaches the local CLI, but the reply back to WeChat can fail until one message has been sent from WeChat.

### Which cli-wechat-bridge commands are not documented?

`wechat-check-update` and `wecom-check-update`. The package declares fourteen binaries in total, seven with a `wechat-` prefix and seven with a `wecom-` prefix, and the README covers the other twelve across its setup, launch, and daemon sections.

## Sources

- [License: AGPL-3.0](https://github.com/UNLINEARITY/CLI-WeChat-Bridge/blob/main/LICENSE)
- [Project website](https://unlinearity.github.io/CLI-WeChat-Bridge/)
- [README](https://github.com/UNLINEARITY/CLI-WeChat-Bridge/blob/main/README.md)
- [Releases](https://github.com/UNLINEARITY/CLI-WeChat-Bridge/releases)
- [UNLINEARITY/CLI-WeChat-Bridge on GitHub](https://github.com/UNLINEARITY/CLI-WeChat-Bridge)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/unlinearity-cli-wechat-bridge