pi-wechat

English | 简体中文

pi-wechat is a TypeScript extension for pi that bridges WeChat iLink Bot conversations into a pi session.

It lets you:

• log in to WeChat iLink Bot with a QR code
• long-poll incoming WeChat messages in the background
• inject each incoming message into the current pi session
• send the final assistant reply from the completed agent loop back to WeChat
• keep WeChat typing state in sync while pi is working

What This Extension Is

This project is a pi extension, not a standalone chatbot process.

The bridge works by feeding WeChat messages into the current pi session. That design keeps the implementation small and aligned with pi's extension model, but it also means the session becomes the shared context for all bridged messages.

Recommended usage:

• run the bridge in a dedicated pi session
• avoid mixing manual terminal prompts and live WeChat traffic in the same session

Current scope:

• stable text message bridge
• login persistence
• retry and session-expiry handling
• typing indicator support

Current limitations:

• image, voice, video, and file messages are converted to placeholder text
• this is not a multi-user routing server
• this does not isolate each WeChat conversation into a separate pi session

Install

Install the extension with pi using one of these package sources.

Option A: install from npm

pi install npm:pi-wechat

Option B: install from GitHub

pi install git:github.com/yangyang0507/pi-wechat

Reload pi resources

If pi is already running:

/reload

Quick Start

Inside pi:

/wechat-login
/wechat-start

Then:

1. scan the QR code in pi with WeChat
2. confirm the login on your phone
3. send a message to the bot from WeChat
4. wait for pi to finish the full agent loop
5. receive the final assistant text reply back in WeChat

Usage Tutorial

Login

Run:

/wechat-login

The extension fetches a WeChat iLink Bot QR code, renders it in the pi UI, and waits for confirmation.

Credentials are stored locally at:

~/.pi-wechat/credentials.json

To force a fresh login:

/wechat-login --force

Start the bridge

Run:

/wechat-start

This starts the long-poll loop. Incoming WeChat messages are queued and injected into the current pi session one by one.

Stop the bridge

Run:

/wechat-stop

This stops polling and clears in-memory bridge state.

Check bridge status

Run:

/wechat-status

This shows whether the bridge is running, whether credentials are loaded, and whether there are queued messages.

Clear saved credentials

Run:

/wechat-logout

This stops the bridge and removes the local credential file.

Slash Commands

• /wechat-login - log in with QR code
• /wechat-login --force - force a fresh QR login
• /wechat-start - start polling and bridging messages
• /wechat-stop - stop the bridge
• /wechat-status - show bridge state
• /wechat-logout - remove saved credentials and stop the bridge

How Replies Work

When a WeChat message arrives:

1. the extension receives it from the iLink Bot API
2. the message text is injected into pi as a user message
3. bridge-specific reply instructions are added through the hidden before_agent_start system prompt layer
4. pi runs the full agent loop, including tools if needed
5. after agent_end, the extension extracts the final assistant text
6. that final text is sent back to WeChat

This is intentional: replying on agent_end avoids prematurely sending intermediate turn results when the assistant uses tools.

Development

Install dependencies:

npm install

Run a basic extension load check:

npm run check

Publish

Once you are ready to distribute it through npm:

npm run check
npm login
npm publish --access public

Debug Logging

By default, the extension keeps UI noise low and avoids extra console logging when pi UI notifications are available.

To enable bridge debug logs:

PI_WECHAT_DEBUG=1 pi

References

• pi extension runtime: badlogic/pi-mono
• WeChat protocol SDK reference: epiral/weixin-bot
• Agent bridge design reference: wong2/weixin-agent-sdk