GreenBubbles CLI
GreenBubbles reads your WeChat history on a Mac, searches chats and feeds agents for cited notes. The key is captured by hand.
- 423 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Captures the encryption key from running WeChat with administrator rights and re-signs the app.
- Private chats go to the cloud model provider unless the agent runs locally.
Install
- Works in
Manual install
brew tap bojieli/greenbubbles https://github.com/bojieli/greenbubbles.git
brew install bojieli/greenbubbles/greenbubblesThe first two commands in the README Install section add the tool through Homebrew.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Captures the encryption key from running WeChat with administrator rights and re-signs the app.
- Private chats go to the cloud model provider unless the agent runs locally.
This is third-party code. Review the repository files before installing.
What it does
GreenBubbles is a macOS command-line tool that reads WeChat's local encrypted databases with no export and no second copy. `greenbubbles chats` and `greenbubbles messages search` list chats, open messages with attachments and search text. Skills ship with the tool: an agent builds a personal Markdown wiki from chosen conversations, each fact tied to its source message, and later adds only new messages. An encrypted backup with a 24-word recovery phrase is available.
Who it is for. Technical WeChat users on a Mac who want their own conversation history as notes and searchable by an agent.
Good fit when
- An old message needs to be found in your own chats by keyword.
- An agent builds project notes from chosen conversations with citations.
- Notes update with new messages only, with changes visible in Git.
- History is saved to an encrypted backup readable without WeChat.
Not a fit when
- Access to someone else's conversations is wanted; the tool is meant for your own account.
- There is no Apple silicon Mac on macOS 14 or newer, or no administrator rights.
- The goal is reading others' chats or group conversations without the participants' knowledge.
Example request
Find the contract discussion from last month in my WeChat chats and write a note citing the source messages.Limitations
The project is called a research alpha. First setup copies the database key from the running WeChat app, which needs administrator rights and re-signs your copy of the app. This sidesteps protection of local data and may breach WeChat's terms; WeChat updates can break key capture. With a cloud model, messages the agent reads go to that provider. Never paste the key or recovery phrase into prompts.
How to disable. Remove the tool with `brew uninstall greenbubbles` and the skills from the agent directory. Delete the key file `~/.greenbubbles-acquire/passphrase.txt`, notes and backups by hand.
FAQ
Does the tool change WeChat files?
No, the README says it only reads the databases. Notes and backups are created only on request.
Which agents work?
The README names Codex, Claude Code, OpenCode, Kimi Code, Gemini CLI and Grok Build.
Where do messages go?
Reading happens on the Mac. With a cloud model, the provider receives the messages it reads.
What does installation need?
An Apple silicon Mac on macOS 14 or newer and Homebrew; key setup needs an administrator.
How do I revoke access?
Delete the key file `~/.greenbubbles-acquire/passphrase.txt` and the skill from the agent directory. Without the key the tool cannot open the database.
Discussion
No questions or reviews yet.
Related
CLI toolsA skill processes your WeChat favorites on a Mac and builds an HTML report with search, filters and activity charts.
A macOS app keeps a private work timeline, and its local MCP server tells an agent what you did and what is unfinished.
imsg is a macOS command-line tool: an agent reads Messages chats, watches for new messages and sends iMessage and SMS.
Cross-device clipboard sync with a built-in MCP server: the agent reads your copy history, and data never leaves for the cloud
Shelf, highlights and reading stats from WeChat Reading in a chat with your agent: the official Tencent skill
ChatCrystal: notes from agent conversations
ChatCrystal
A local knowledge base: imports Claude Code, Cursor and Codex chats into notes, semantic search and MCP memory
README in short
The README covers reading WeChat's database on a Mac, search commands and note skills, with separate sections on the key, backups and privacy.