Bridge WeChat direct messages to any ACP-compatible AI agent.

wechat-acp 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.

• WeChat QR login with terminal QR rendering
• One ACP agent session per WeChat user
• Built-in ACP agent presets for common CLIs
• Custom raw agent command support
• Auto-allow permission requests from the agent
• Direct message only; group chats are ignored
• Background daemon mode

• Node.js 20+
• A WeChat environment that can use the iLink bot API
• An ACP-compatible agent available locally or through npx

Start with a built-in agent preset:

npx wechat-acp --agent copilot

Or use a raw custom command:

npx wechat-acp --agent "npx my-agent --acp"

On first run, the bridge will:

1. Start WeChat QR login
2. Render a QR code in the terminal
3. Save the login token under ~/.wechat-acp
4. Begin polling direct messages

List the bundled presets:

npx wechat-acp agents

Current presets:

• copilot
• claude
• gemini
• qwen
• codex
• opencode

These presets resolve to concrete command + args pairs internally, so users do not need to type long npx ... commands.

wechat-acp --agent <preset|command> [options]
wechat-acp agents
wechat-acp stop
wechat-acp status

Options:

• --agent <value>: built-in preset name or raw agent command
• --cwd <dir>: working directory for the agent process
• --login: force QR re-login and replace the saved token
• --daemon: run in background after startup
• --config <file>: load JSON config file
• --idle-timeout <minutes>: session idle timeout, default 1440 (use 0 for unlimited)
• --max-sessions <count>: maximum concurrent user sessions, default 10
• --hide-thoughts: do not forward agent thinking to WeChat (default: forwarded)
• -h, --help: show help

Examples:

npx wechat-acp --agent copilot
npx wechat-acp --agent claude --cwd D:\code\project
npx wechat-acp --agent "npx @github/copilot --acp"
npx wechat-acp --agent gemini --daemon

You can provide a JSON config file with --config.

Example:

{
  "agent": {
    "preset": "copilot",
    "cwd": "D:/code/project"
  },
  "session": {
    "idleTimeoutMs": 86400000,
    "maxConcurrentUsers": 10
  }
}

You can also override or add agent presets:

{
  "agent": {
    "preset": "my-agent"
  },
  "agents": {
    "my-agent": {
      "label": "My Agent",
      "description": "Internal team agent",
      "command": "npx",
      "args": ["my-agent-cli", "--acp"]
    }
  }
}

• Each WeChat user gets a dedicated ACP session and subprocess.
• Messages are processed serially per user.
• Replies are formatted for WeChat before sending.
• Typing indicators are sent when supported by the WeChat API.
• Sessions are cleaned up after inactivity (set idleTimeoutMs to 0 to disable idle cleanup).

By default, runtime files are stored under:

~/.wechat-acp

This directory is used for:

• saved login token
• daemon pid file
• daemon log file
• sync state
• anonymous telemetry install id (telemetry-id, see Telemetry section)

• Direct messages only; group chats are ignored
• MCP servers are not used
• Permission requests are auto-approved
• Agent communication is subprocess-only over stdio
• Some preset agents may require separate authentication before they can respond successfully

For local development:

npm install
npm run build

Run the built CLI locally:

node dist/bin/wechat-acp.js --help

Watch mode:

npm run dev

wechat-acp collects anonymous usage telemetry via Azure Application Insights to help understand which agent presets are used and to detect crashes.

To disable telemetry, set the WECHAT_ACP_TELEMETRY environment variable to 0, false, or off before running:

WECHAT_ACP_TELEMETRY=0 npx wechat-acp --agent copilot

What is collected (9 event types only):

• app.start / app.stop — process lifecycle, agent preset name, daemon flag, uptime
• login.success / login.failure / token.reused — WeChat login outcomes (no token, no QR URL)
• message.received — message arrived; only the categorical kind (text / image / voice / file / video / empty) and a hashed user id
• session.created — new ACP session opened
• prompt.completed — ACP turn finished; agent preset, stop reason, duration, reply length
• reply.sent — reply pushed back to WeChat; segment count, total length

Plus exception reports for monitor, prompt, reply, auth, agent_spawn, and enqueue failures.

What is never collected: message bodies, filenames, voice transcripts, image URLs, login tokens, QR codes, raw agent command strings, environment variables, working directory paths, raw WeChat user IDs.

User IDs are sha256-hashed with a per-install salt stored in ~/.wechat-acp/telemetry-id. The salt is generated on first run and never leaves your machine. Delete the file to rotate it.

MIT