# wechat-acp: Bridging WeChat Direct Messages to ACP Agents Like Claude Code and Codex

> wechat-acp is an MIT-licensed TypeScript bridge that logs into WeChat through the iLink bot API, polls 1:1 messages, and forwards them to any ACP-compatible agent over stdio. It answers the WeChat Claude Code and ACP adapter searches, but it is direct-message only and the README leaves several operational questions open.

**formulahendry/wechat-acp** — Bridge WeChat chat messages to any ACP-compatible AI agent (Claude, Codex, Copilot, Qwen, Gemini, OpenCode, OpenClaw, Hermes, Kiro, Kimi, Pi and more)

- Repository: https://github.com/formulahendry/wechat-acp
- Website: https://www.npmjs.com/package/wechat-acp
- Stars: 840 · Forks: 106
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/formulahendry-wechat-acp

## The gap wechat-acp fills between WeChat and an ACP agent

Most ACP agents are designed to be driven from an editor or a terminal. wechat-acp inverts that: the agent stays on your machine, and the conversation arrives from WeChat. The README describes the flow 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. That is the whole product. It is for engineers who already have an ACP-compatible agent installed or reachable through npx and who want a chat front end without writing a bot server. The repository topics (acp, agent-client-protocol, wechat-bot, weixin) confirm the intended audience. It is not a general WeChat automation framework, and it is not an agent itself; it ships no model and no reasoning of its own.

## How the bridge moves a message: QR login, stdio forwarding, one session per user

The architecture is deliberately thin. On first run the bridge starts WeChat QR login, renders a QR code in the terminal, saves the login token under ~/.wechat-acp, and begins polling direct messages. Each WeChat user gets one ACP agent session, and the agent process is spawned with the command and args that a preset resolves to internally, or with the raw command you pass to --agent. Communication with the agent is over stdio, which is why any ACP-compatible CLI works without an HTTP endpoint. Output comes back through the same channel: agent image output is delivered as native WeChat image messages, and audio, embedded resources and generated files are also delivered. Permission requests from the agent are auto-allowed, which is a design choice worth pausing on. Group chats are ignored by design. Sending is one-directional per user session unless you use the inject subcommand, which enqueues a local text message for the running daemon. The ACP SDK version pinned in package.json is ^0.16.1, so the protocol surface is whatever that SDK exposes.

## Install and first run: npx wechat-acp with a built-in preset

There is no global install step in the README; the documented path is npx. Node.js 20 or newer is required, and package.json sets engines.node to >=20.0.0. The quickest start uses a built-in preset. Run this in a terminal where you can scan a QR code with your phone:

```bash
npx -y wechat-acp@latest --agent copilot
```

On first run the bridge starts WeChat QR login, renders the QR code in the terminal, saves the token under ~/.wechat-acp, and begins polling direct messages. If you would rather drive a custom agent, pass the raw command instead. The README gives this shape:

```bash
npx -y wechat-acp@latest --agent "npx my-agent --acp"
```

To see which presets ship with the version you just pulled, run the agents subcommand. It prints the bundled list, which currently includes copilot, claude, gemini, qwen, codex, opencode, openclaw, kiro, hermes, kimi and pi:

```bash
npx wechat-acp agents
```

For a long-running setup, --daemon backgrounds the process, and the status and stop subcommands manage it. A working directory can be pinned so the agent operates inside a specific project:

```bash
npx -y wechat-acp@latest --agent claude --cwd D:\code\project --daemon
npx -y wechat-acp@latest status
```

If you want to try unreleased work, every push to main is published under the next dist-tag. The README warns these builds have not been through release review. Stable users are told to keep using @latest.

## Configuration file keys and the session resume modes

Anything you can pass on the command line has a JSON equivalent behind --config. The README gives a full example, and the keys are nested under agent and session. Note the camelCase keys: resourceInlineLimit, idleTimeoutMs, maxConcurrentUsers, resume, turnEndMessage, showDiffs.

```json
{
  "agent": {
    "preset": "copilot",
    "cwd": "D:/code/project",
    "showDiffs": true,
    "resourceInlineLimit": 1000
  },
  "session": {
    "idleTimeoutMs": 86400000,
    "maxConcurrentUsers": 10,
    "resume": "auto",
    "turnEndMessage": "Turn complete"
  }
}
```

The resume key is the one that changes behaviour most. off, the default, always starts a new ACP session. auto loads a saved session when the agent advertises the ACP loadSession capability, and starts fresh when loading is unsupported or the saved session is gone, but surfaces other load failures. required demands that an existing saved session load successfully, though a user with no saved session can still start their first conversation. Session IDs are saved only after the first prompt completes, so a crash before that point leaves nothing to resume. That is a real constraint, not a footnote.

## Direct messages only, auto-allowed permissions, and the iLink dependency

Three limitations matter more than the feature list suggests. First, the bridge is direct-message only; group chats are ignored. If your team works in WeChat groups, this tool does not fit, and no flag in the README changes that. Second, permission requests from the agent are auto-allowed. For a personal agent on your own machine that may be acceptable, but it removes the confirmation step that ACP otherwise provides, and the README documents no way to turn it off. Third, the whole thing depends on a WeChat environment that can use the iLink bot API. That is an environmental precondition, not a code path you can patch. If your account or region cannot use iLink, the bridge cannot log in regardless of the agent you choose. There is also a single-bridge assumption baked into the default paths: token, daemon pid and log, sync state and telemetry id all live under ~/.wechat-acp, so a machine hosts one bridge unless you namespace it with --instance. And auto-allow plus a daemon plus a chat interface means the agent is reachable by anyone who can message that WeChat account.

## Running several bridges side by side with --instance

The instance flag is the answer to the single-bridge limit. Passing --instance <name> moves everything under ~/.wechat-acp/instances/<name>/, which lets several bridges run at once, each with its own WeChat account and project directory. The README's typical setup is two WeChat accounts driving two repositories. Each instance prints its own QR code on first run, and tokens are saved per instance, so later runs reuse them independently. The stop and status subcommands honour the same flag:

```bash
npx -y wechat-acp@latest --instance projA --agent copilot --cwd D:\code\repo-a
npx -y wechat-acp@latest --instance projB --agent copilot --cwd D:\code\repo-b
npx -y wechat-acp@latest status --instance projA
npx -y wechat-acp@latest stop --instance projB
```

Without --instance, paths fall back to ~/.wechat-acp exactly as before, so existing installs are unaffected. The trade-off is that each instance needs its own WeChat account, which in practice means each needs its own phone number or login identity. That is an operational cost the README does not soften.

## How wechat-acp differs from ACP editor integrations and MCP servers

The closest alternatives are not other WeChat bots but other ACP front ends. Editor integrations such as the ACP support in VS Code or Zed drive the same agents from a code editor, where the agent sees your workspace and you see diffs inline. wechat-acp drives the same agents from a chat app, where the agent sees whatever --cwd points at and you see text messages. The transport is the same stdio protocol; the surface is entirely different. If your goal is reviewing diffs, an editor integration is the better tool, and wechat-acp's --show-diffs flag only forwards diffs to chat rather than rendering them for review. A second alternative is an MCP-based bridge, which exposes tools to a model rather than forwarding whole conversations to an agent. wechat-acp depends on @modelcontextprotocol/sdk, so MCP is present in the dependency tree, but the product is an ACP client, not an MCP server. Pick it when the requirement is chat reachability, not tool exposure.

## Licence, upgrade cost and what the README does not cover

The licence is MIT, stated in package.json and present as a LICENSE file at the repository root. MIT permits commercial use and modification with attribution and no warranty, which is the usual trade for a bridge of this kind; that is a description of the licence text, not legal advice. Upgrade cost is low if you stay on @latest, because the package is distributed through npm and invoked via npx, so there is no compiled artefact to rebuild. The repository also publishes every push to main under the next dist-tag with versions shaped like 0.7.1-next.202605311530.abc1234, which is convenient for testing but explicitly not release-reviewed. The last push was on 2026-08-15, and the most recent tagged release is v0.10.0 from 2026-07-25, so the project is moving but the release cadence is slower than the commit cadence. What the README does not document: rollback of a bad upgrade, rate limits on the iLink polling path, how the auto-allow permission behaviour can be disabled, and what happens to in-flight agent turns when the daemon is stopped. Treat those as unknowns to test in your own environment rather than assume.

## Conclusion

Adopt wechat-acp if you already run an ACP-compatible agent locally and want to reach it from WeChat direct messages without building a bot backend. Do not adopt it if you need group chat support, a web UI, or a guarantee that a restart will restore every conversation, because session resume depends on the agent advertising the ACP loadSession capability and the default is off. Before committing, verify three things: that your WeChat environment can use the iLink bot API at all, that your chosen agent responds to the ACP handshake, and whether you want --session-resume auto or required instead of the default off. Run npx wechat-acp agents first to confirm your agent is among the eleven bundled presets.

## FAQ

### Which ACP agents does wechat-acp support out of the box?

The README lists eleven built-in presets: copilot, claude, gemini, qwen, codex, opencode, openclaw, kiro, hermes, kimi and pi. You can also pass a raw command to --agent, so any ACP-compatible CLI reachable through npx works.

### Does wechat-acp work with WeChat group chats?

No. The README states that the bridge is direct message only and that group chats are ignored, and no option is documented to change this.

### Where does wechat-acp store the WeChat login token?

The login token is saved under ~/.wechat-acp on first run. When you pass --instance <name>, all state including the token moves under ~/.wechat-acp/instances/<name>/ so multiple bridges can coexist.

### What does the --session-resume option do in wechat-acp?

It controls whether each WeChat user's ACP conversation is restored after the bridge restarts. off, the default, always starts a new session; auto loads a saved session when the agent advertises the ACP loadSession capability; required demands a successful load. Session IDs are saved only after the first prompt completes.

## Sources

- [formulahendry/wechat-acp on GitHub](https://github.com/formulahendry/wechat-acp)
- [License: MIT](https://github.com/formulahendry/wechat-acp/blob/main/LICENSE)
- [Project website](https://www.npmjs.com/package/wechat-acp)
- [README](https://github.com/formulahendry/wechat-acp/blob/main/README.md)
- [Releases](https://github.com/formulahendry/wechat-acp/releases)

---

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