wechat-acp: a stdio bridge from WeChat direct messages to ACP agents

The gap wechat-acp fills: WeChat as an agent client

Most ACP agents assume a desktop client. The Agent Client Protocol is a stdio protocol, so the client has to be a process that can spawn the agent, write JSON to its stdin and read from its stdout. A phone cannot do that. wechat-acp inserts itself as that process and exposes the conversation through WeChat direct messages instead. The README describes the loop plainly: the bridge logs in with the WeChat iLink bot API, polls incoming 1:1 messages, forwards them to an ACP agent over stdio, and sends the agent reply back to WeChat. The audience is narrow and identifiable. You need a WeChat environment that can use the iLink bot API, Node.js 20 or later, and an ACP-compatible agent available locally or through npx. That combination points at an individual developer who already runs a coding agent on a workstation and wants to reach it from the phone in their pocket, not at a team provisioning a shared assistant. The single-user framing shows up again in the session model: one ACP agent session per WeChat user, capped at ten concurrent users by default.

Polling, stdio and one agent process per WeChat user

The transport is polling, not a webhook. The bridge holds a WeChat login token, asks the iLink bot API for new direct messages on an interval, and maps each sender to an ACP session. That session is a child process speaking ACP over stdio; the bridge writes the user message into it and reads events back. The event stream is where the interesting decisions live, because ACP agents emit more than final answers. Thinking output is forwarded to WeChat by default and suppressed with --hide-thoughts. File diffs are hidden by default and forwarded with --show-diffs. Tool call images are suppressed with --hide-images, but images the agent sends as explicit messages still go through. Audio is forwarded unless --hide-audio is set, and intermediate tool resources are forwarded unless --hide-resources is set. Long tool text resources are rendered inline up to --resource-inline-limit characters, default 1000, with a documented range of 0 to 4000; longer ones become file attachments, and 0 attaches all non-empty tool text resources. Received binary files land in --inbox-dir, defaulting to <storage.dir>/inbox, and the agent is told the absolute path so it can read the file itself. Passing --no-inbox removes that and leaves the agent with only a size notice. That is a coherent design: the bridge is a rendering and routing layer, and the agent keeps doing the work.

Getting a bridge running: presets, flags and the config file

The shortest path is a preset. The README gives npx -y wechat-acp@latest --agent copilot, and npx wechat-acp agents lists the bundled names: copilot, claude, gemini, qwen, codex, opencode, openclaw, kiro, hermes, kimi and pi. Presets resolve to concrete command and args pairs internally, which is the whole point of having them. Anything not on the list goes in as a raw command, for example npx -y wechat-acp@latest --agent "npx my-agent --acp". On first run the bridge starts WeChat QR login, renders the QR code in the terminal, saves the login token under ~/.wechat-acp, and begins polling. If you prefer a file over flags, --config takes JSON with an agent block and a session block. The README example sets agent.preset to copilot, agent.cwd to a Windows path, agent.showDiffs to true, agent.resourceInlineLimit to 1000, and in the session block idleTimeoutMs to 86400000, maxConcurrentUsers to 10, resume to auto and turnEndMessage to a completion string. The flag equivalents are --idle-timeout in minutes (default 1440, with 0 for unlimited), --max-sessions (default 10), --session-resume, and --turn-end-message, which is disabled by default. There is also --daemon to background the process after startup, plus stop and status subcommands, and inject --text for pushing a local message into the running daemon.

Auto-allow permissions is the design choice you have to accept

The feature list includes auto-allow permission requests from the agent, and that single line determines where this tool belongs. An ACP agent that wants to write a file or run a command normally asks the client for permission. Here the client is a chat bridge, and it approves. The README presents this as a feature rather than a configurable policy, and no flag is documented for turning it off or for routing permission prompts to WeChat. Combine that with --cwd, which sets the working directory for the agent process, and the trust boundary becomes concrete: anyone who can send a direct message to the logged-in WeChat account can drive an agent that writes files and runs commands in that directory without further confirmation. The bridge does not add an allowlist, a confirmation step or a per-user policy in the documented surface. Treat wechat-acp as a personal remote control for an agent you already trust on a machine you control. It is the wrong tool if you want a human in the loop for each write, or if the WeChat account is shared, or if the working directory holds anything you would not let a chat message modify.

Group chats are ignored, and that is a load-bearing limitation

The feature list states it without hedging: direct message only, group chats are ignored. There is no documented configuration to change this, no mention of @-mentions, no per-group routing. For a personal bridge this is a sensible reduction, since group membership would make the one-session-per-user mapping ambiguous and the auto-allow policy untenable. For anyone hoping to drop a bot into a team group and let colleagues query a shared agent, the project does not do it today. The session limits reinforce the same reading. --max-sessions defaults to 10, so an eleventh concurrent user is not served, and sessions expire on an idle timeout of 1440 minutes by default. A long-running conversation with a single user is fine. A burst of distinct users is not what the defaults are shaped for. If you need multi-user access, the honest options are running several instances against separate WeChat accounts, or building something else on top of the ACP agent directly.

Session resume: off, auto and required

Restarting the bridge is the moment where the session model becomes visible. --session-resume takes three values and defaults to off, which means every restart begins a new ACP session and the agent loses the thread. auto loads a saved session when the agent advertises the ACP loadSession capability; if loading is unsupported or the saved session no longer exists it starts fresh, but it surfaces other load failures rather than hiding them. required insists that an existing saved session load successfully, though a user with no saved session can still start their first conversation. The README notes that session IDs are saved only after the first prompt completes, and that loading replays history at the ACP protocol level. Two practical consequences follow. First, resume quality depends on the agent, not on wechat-acp, so the value of auto varies by preset. Second, switching an existing deployment from the default off to auto or required changes what a restart means, and the difference between auto and required is whether a broken load is a warning or a hard stop. Pick deliberately rather than leaving it at the default and being surprised.

Isolation, storage layout and the upgrade path

By default the saved login token, daemon pid and log, sync state and telemetry id all live under ~/.wechat-acp, which the README says means a single machine can only host one bridge at a time. --instance <name> namespaces all of that under ~/.wechat-acp/instances/<name>/ so several bridges can run side by side, each with its own WeChat account and project directory. The README's example is two terminals, two accounts, two repos, with status --instance projA and stop --instance projB to address them. Without --instance, paths fall back to the old location, so existing installs are unaffected. On upgrades, the project publishes every push to main under the next dist-tag, with versions tagged like 0.7.1-next.202605311530.abc1234, built after CI passes but without release review. That is a genuine convenience and a genuine risk: the README itself says to expect rough edges and that stable users should stay on wechat-acp@latest. The licence is MIT, which permits commercial and private use and modification, but this is not legal advice and you should read the licence text and your own obligations rather than taking a summary from an article.

Where wechat-acp sits next to a plain ACP client

The obvious alternative is the ACP client you would otherwise use: a terminal or editor front end that spawns the agent directly over stdio. That approach gives you the full permission flow, a real diff view and an interactive session, and it costs you nothing in WeChat surface area. wechat-acp trades those away for reach. It renders agent output into WeChat message types, sends images as native WeChat images, delivers audio and generated files, and saves received files to an inbox directory so the agent can read them by path. The trade is explicit: to get the conversation onto a phone, the bridge flattens the interaction into messages and auto-approves what the agent asks for. A second alternative is writing your own relay against the iLink bot API and the ACP spec, which is what this project already is; the reason to use wechat-acp rather than rebuild it is the preset table, the inbox handling, the instance namespacing and the resume modes. If none of those matter to you, the plain ACP client is the smaller system. If reaching the agent from WeChat is the requirement, this is the piece that exists.

Editorial conclusion

Adopt wechat-acp if you want a personal WeChat channel into an ACP agent you already run locally, and you accept that the bridge auto-allows every permission request and ignores group chats. Do not adopt it as a shared team bot or as an agent runtime: it is a relay, not a sandbox, and its session model is one ACP process per WeChat user. Before rolling it out, run npx wechat-acp agents to confirm your CLI has a preset, then decide --session-resume and --max-sessions deliberately, because the defaults are off and 10.

Official sources

1. formulahendry/wechat-acp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases