WeChat Mac Visual Automation
Read WeChat on a Mac through visual perception, then use an Agent to decide and send replies.
- Source repo
- wq19901103wq/wechat-mac-rpa
- Stars
- ★ 125
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 49/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specific
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Individuals who want a bot on their own Mac to handle unread WeChat chats and reply using a local persona.
- Not a fit if
- Users who need a cross-platform deployment
- Teams that cannot send chat prompts or screenshots to a configured external API
- Source review
- 49/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
This macOS framework automates WeChat by treating it as a black-box GUI, using screenshots, visual recognition, and system-level UI control. Its python3 run_bot.py entry point runs a recurring loop that perceives the window, deduplicates messages across ticks, lets an Agent choose a reply or tool, and acts through UIInteractor. SmartPipeline uses pixel differences to decide when to call a multimodal API, while VisionPipeline provides local OCR fallback; optional WeFlow imports history from a user-authorized local database copy to initialize memory. Memory combines working and session context, an LLM Wiki, and BGE vector search, with runtime data and indexes stored locally. The repository also includes a FastAPI admin interface, structured logs, and benchmark tools; deployment requires macOS permissions, and external model use sends relevant prompts or screenshots to the configured provider.
After installing dependencies and configuring an API key in .env plus a persona in data/persona.md, run python3 run_bot.py. The bot captures the WeChat window with screencapture; SmartPipeline checks pixel differences and, when the view changes, calls a multimodal API to extract messages and layout, while VisionPipeline offers local OCR as a fallback. GlobalStore deduplicates across ticks using LCS and related matching, then passes new messages to the lightweight Agent's ReAct loop. The Agent can call tools such as search_memory, web_search, and browse_url, or route to the Hermes path when configured. The action layer uses AppleScript, cliclick, and UIInteractor to switch chats, send text or files, and handle login recovery. New messages can feed memory retrieval, and optional WeFlow can export history from a user-authorized local database copy. Outputs include replies in the WeChat UI, SQLite chat records, memory and vector indexes, structured runtime logs, and benchmark reports.
- Individuals who want a bot on their own Mac to handle unread WeChat chats and reply using a local persona.
- WeChat users who want the Agent to retrieve chat history and person-specific Wiki notes before replying.
- Users who need to send files from the configured shareable-file allowlist into WeChat chats.
- Developers who need a local OCR fallback when the visual API is unavailable.
- Maintainers who need to inspect tick logs, review labeled cases, or run benchmarks.
How do you install or deploy this agent?
Requires macOS 12+, Python 3.10+, and WeChat for Mac. Grant Screen Recording and Accessibility permissions to the app that runs the bot, and authorize Automation when prompted. The documented install and configuration steps are:
pip install -r requirements.txt
cp .env.example .env
cp prompts/persona.md.example data/persona.mdPut the API key in .env and the persona in data/persona.md. The README does not specify the exact provider or required variable names in .env; use the repository's configuration template. External LLM or multimodal APIs require network access.
How do you use this agent?
Start the bot in the foreground:
python3 run_bot.pyFor a persistent admin service, the README documents this LaunchAgent setup:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.wechat-mac-rpa.admin.plist
launchctl enable gui/$(id -u)/com.wechat-mac-rpa.admin
launchctl kickstart gui/$(id -u)/com.wechat-mac-rpa.adminRun the admin interface in the foreground for debugging:
python3 scripts/admin.pyBuild the long-term history index with:
python3 scripts/update_history_index.pyWhat are this agent's strengths and limitations?
- The default SmartPipeline mode uses screenshots and public macOS APIs; it does not rely on protocol reverse engineering, database reads, or code injection.
- SmartPipeline skips multimodal API calls when pixel checks find no meaningful change, and VisionPipeline offers a local OCR fallback.
- Working, session, and long-term memory are combined;
search_memoryretrieves both Wiki summaries and original chat excerpts. - Structured tick logs, benchmarks, human review, and an LLM Judge form a documented quality evaluation and iteration workflow.
- The documented runtime is limited to macOS 12+ and requires WeChat for Mac plus Screen Recording and Accessibility permissions.
- When external LLM or multimodal APIs are enabled, relevant prompts or screenshots go to the configured provider; pricing is not specified in the README.
- Setup involves API configuration and local persona/runtime data, with optional WeFlow history initialization, beyond a one-command install.
- The README does not enumerate supported LLM providers or document a deployment path for other platforms.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| WeChat Mac Visual Automation This agent | 49 · Major gaps | CLIFree + model costs | ★ 125 | today | Python | — |
| Nuphus Desktop Automation MCP | 72 · Some gaps | MCP serverFree + model costs | ★ 328 | 3d ago | Rust | Claude.ai · OpenAI API · Claude API |
| Clawd Cursor | 74 · Some gaps | MCP serverFree + model costs | ★ 406 | today | TypeScript | Codex · Claude Code |
| Agent Desktop | 85 · Good | CLIFree | ★ 1.8k | today | Rust | — |
How does FollowAgents rate this agent?
Why each dimension lost points
The README explains the purposes of Accessibility, Screen Recording, and Automation permissions, discloses local chat data, the optional WeFlow database-copy path, and prompts or screenshots sent to configured LLM providers, and advises against committing keys or chat data. These support partial credit for transparency and sensitive-data handling. Deductions: the bot automatically switches chats and sends messages or files, with no per-send confirmation documented; system permissions and external effects are substantial, while recovery is limited to a database backup script and does not address mistaken messages; the dependency list has no audit or vulnerability-mitigation evidence; publisher identity and code attribution are unverified.
The README, quickstart, and troubleshooting guides provide layered descriptions, log-based diagnostic procedures, and concrete failure cases, while the test excerpt shows some action-failure handling. Deductions: some guide paths and directory references appear inconsistent with the repository overview, including references to removed legacy code and differing test locations; most dependencies use ranges or older pins without availability assurances. CI configuration and test files provide some evidence, but do not establish that anything passed in this review.
The documentation targets WeChat automation on macOS, states macOS/Python requirements, describes OCR/SmartPipeline and optional WeFlow paths, discloses provider data transfer, and gives troubleshooting guidance. It describes module and optional-capability boundaries in useful detail. Deductions: the materials do not fully establish the triggering conditions or user controls for each outgoing reply, and the supported setting is largely limited to a particular platform, application, and Chinese-language context.
The README includes a contents structure, architecture diagrams, repository layout, glossary, documentation index, and quickstart; the MIT license text is complete. Installation, configuration, FAQ, troubleshooting, and some limitations are covered. Deductions: parts of the quickstart refer to legacy paths or test locations that do not align with the current repository overview; the materials do not provide a clear release policy, changelog, or named maintenance responsibility, and publisher identity is unverified.
The project describes an end-to-end path from screenshots and message processing to automated replies, with practical features such as configurable persona, memory retrieval, logs, and an admin interface. Deductions: marginal benefit and operating cost are not quantified. Benchmark figures are listed, but the supplied materials lack the underlying datasets, evaluation protocol, or reviewable result files; external model calls and ongoing maintenance also incur costs.
Architecture, permissions, data flows, and diagnostic procedures are described concretely, and the CI workflow and action-test excerpt corroborate some engineering claims. Deductions: many performance, quality, and production-readiness claims are README assertions without raw benchmark results or independent corroboration; the materials only partly distinguish design claims from behavior actually verified.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- The bot can switch WeChat chats and send replies or allowlisted files automatically. Review reply policy, file allowlists, and host permissions before deployment; no visible recovery for mistaken messages is documented.
- When external multimodal or LLM services are enabled, chat prompts or screenshots go to the configured provider. WeFlow also imports local chat history, so assess data authorization and retention scope.
- The README's benchmark figures are not accompanied by raw data or an evaluation protocol in the supplied materials, so they are not independently verified here.