Pi Remote WeCom

English · 简体中文

Control your local Pi coding agent from WeCom on your phone. One bot connects to a local daemon that manages multiple Pi sessions.

• Resume a running session or find a previous conversation.
• Create terminal or background sessions, send text and attachments, switch models, and stop tasks.
• Keep terminal tab titles and phone session names in sync, with optional model-generated names.
• Connect directly through the official WeCom WebSocket SDK. No public server or callback endpoint is required.

Screenshots

Install

Requires macOS, Node.js ≥22.19, Pi Coding Agent (tested with 0.87.1), and a dedicated WeCom intelligent bot with API mode → persistent connection enabled. A regular group webhook bot is not sufficient. Feature availability depends on your enterprise; use with external enterprise accounts has not been separately verified.

Install from npm:

pi install npm:pi-remote-wecom

Or from Git:

pi install git:github.com/KKinsz/pi-remote-wecom

Alternatively, install from a source checkout:

npm ci --ignore-scripts
pi install "$PWD"

1. Create a dedicated intelligent bot in WeCom and copy its BotID and Secret. Share it with yourself so you can find it on your phone. Do not reuse a bot connected to another client.
2. In Pi, run /reload, then /remote setup. Enter the BotID and Secret and choose binding by code. The extension starts the daemon, registers macOS login startup, and displays a six-digit code locally.
3. Send that code in a direct message to the bot. After binding succeeds, choose 活跃会话 or send ls to select a session. Only the bound account can control Pi.

The UI and bot replies are currently primarily in Chinese. English command aliases are supported.

Optional naming: run /tabmodel to choose a naming model. New sessions are named from their first input; /tabmodel reset disables this. Without a naming model, no naming request is made and the session list uses the first input.

Commands

On your phone, select a session and send a message to continue it.

Send an image or file, then add instructions within five minutes. Up to four attachments are accepted per batch (a project limit); each may be at most 100 MiB (104,857,600 bytes), implemented from WeCom's documented "100M" callback limit, which states no exact byte definition — inbound only. Completed tasks send their results back; long results arrive as a Markdown file, and outbound files are bounded by the SDK's chunked upload at roughly 50 MiB.

In Pi:

Terminals and configuration

Adapters are provided for Ghostty, cmux, iTerm2, WezTerm, kitty, and tmux. Automatic selection uses an available terminal; if none is available or the screen is locked, session creation can fall back to background mode. Opening a terminal tab may change focus.

Set terminal in ~/.config/pi-remote-wecom/config.json, then run /remote restart while idle:

Use auto for automatic selection or none for background sessions only. See configuration examples and terminal setup details.

macOS is the primary supported platform. Other systems can run node bin/remote.mjs run in the foreground, but full platform support is not claimed.

Updates and removal

For a source checkout, update the code and run npm ci --ignore-scripts. For Pi-managed Git/npm installs, use pi update --extensions; pinned versions or tags require changing the source explicitly. Then run /reload in Pi and /remote restart while idle. Restart after dependency updates as well.

Before removing the package, run node bin/remote.mjs uninstall from its installed directory to stop the daemon and remove login startup. Then run pi remove <original-install-source> and /reload. Removing the Pi package alone does not remove its launchd service. Configuration, logs, and attachments remain in ~/.config/pi-remote-wecom/ for manual cleanup.

Validation and boundaries

The maintainer has confirmed real-device testing of the main workflow and major commands. Automated checks also cover offline Pi loading, session routing, binding, deduplication, attachments, and card callbacks. This does not claim exhaustive validation of every terminal, external enterprise account, or sleep/network failure scenario.

Only the bound user's direct messages are accepted. The computer must remain awake and online. Background sessions have the same capabilities as terminal sessions: they load your installed extensions and can read, write, and run commands. Opening a background session with pi -r moves it into that terminal; if it is still running, the terminal waits for it to finish and then reloads automatically.

Extension prompts on the phone: during a phone-initiated task, extension confirmations and selections (for example computer-use authorization) are sent to WeCom as cards; in terminal sessions whichever side answers first wins. Unanswered prompts follow remoteConfirm: ask-then-allow (default; allow after remoteConfirmTimeoutMs, 10 minutes), ask (deny on timeout), or allow (allow without asking). Text-input prompts cannot be filled on the phone: background sessions cancel them, terminal sessions keep them open on the computer until the timeout. If an extension asks for confirmation while a background session is starting, creation fails with a hint to use a terminal session.

Question tools on the phone: compatible with Pi's example question / questionnaire tools and AskUserQuestion-style tools (e.g. @juicesharp/rpiv-ask-user-question; multi-select questions use multi-select cards). Unrecognized blocking prompts trigger a reminder to handle them on the computer. In the currently bound terminal session (turns started from either the computer or the phone), questions are sent as WeCom cards with the session name in the card description; questions from unbound sessions are held back and sent once you switch to that session; when free-form answers are allowed, tap "write your own" or simply reply with text (while the current session has a pending question, a plain message is taken as the answer). Multiple questions are asked one by one; whichever side answers first wins; unanswered questions are cancelled on timeout. Background sessions are not supported.

Credentials stay on the local machine, but setup does not mask the Secret input. See security and data handling.

Development

npm ci --ignore-scripts
npm run check
npm run test:package

Tests use isolated temporary directories and fake credentials, without changing your Pi settings, starting launchd services, or calling a model. See Contributing for workflow and Releasing for distribution.

MIT License · Changelog · Source notices · Pi package format