greenbubbles-context

GreenBubbles is a Mac command-line tool for reading your own WeChat history. It reads the database files WeChat already keeps on your Mac, so there is no export step and no second copy to keep up to date. You can:

• browse and search your chats on your own computer;
• ask a coding agent you already use (Claude Code, Codex, and others) to turn chosen conversations into Markdown notes that cite the original messages;
• make an encrypted backup you can open later, even without WeChat.

Research alpha. Needs a Mac with Apple silicon and macOS 14 or later. Setup copies a key out of your own WeChat app, which needs administrator access. Reading and searching happen entirely on your Mac. If you use a cloud AI, the messages it reads are sent to that AI's provider.

What you can do

• Browse and search: list chats, read messages, and open attachments.
• Build notes about your life: have your coding agent write a private wiki from your chats: one short article per part of your life, each fact tied to the message it came from. Passwords and keys pasted into chats stay out.
• Keep notes current: later runs add only new messages, and Git records every change so you can review it.
• Back up: make an encrypted copy of your history, protected by a 24-word recovery phrase.

GreenBubbles never changes WeChat's files; it only reads them. Backups and notes are created only when you ask for them.

Install

You need macOS 14 or later on Apple silicon. Install the command-line tool with Homebrew:

brew tap bojieli/greenbubbles https://github.com/bojieli/greenbubbles.git
brew install bojieli/greenbubbles/greenbubbles

If Homebrew says the formula is untrusted, run this and then repeat the two commands above. Older Homebrew versions don't have brew trust and don't need it.

brew trust --formula bojieli/greenbubbles/greenbubbles

Prefer an app? Download the DMG from Releases and drag GreenBubbles to Applications. It is Developer ID signed and Apple notarized. Releases also include the command-line tool as a ZIP. See CLI releases and Homebrew to verify downloads or upgrade.

You need Swift 6, Xcode's command-line tools, and Rust:

git clone https://github.com/bojieli/greenbubbles.git
cd greenbubbles
cargo build --locked --release --manifest-path Native/GreenBubbles/Cargo.toml
swift build --product greenbubbles-history
swift run greenbubbles-history

The command-line tool is built at Native/GreenBubbles/target/release/greenbubbles. The app asks for this path the first time it runs.

Getting your database key

WeChat encrypts its chat databases. To read them, GreenBubbles needs your account's key, which it copies from your running WeChat app one time.

This one-time setup needs administrator access and re-signs your copy of WeChat. The key setup guide has the steps and troubleshooting help. The key is saved to ~/.greenbubbles-acquire/passphrase.txt, a file only your account can read.

After that, commands work with no extra arguments: they find your WeChat data and key on their own. You need a query profile only to read a second WeChat account or a backup.

Usage

Once the key is set up, these commands read your live WeChat data:

Browse as you would in WeChat: list conversations, then open the one you want. You can use its nickname, remark, alias, or exact ID:

greenbubbles chats
greenbubbles messages list --conversation "Alice"

Replace "keyword" with the text to search for. --query "text" supplies it as a command-line argument. For interactive or piped input, use --query-stdin instead: run the command, type the search on the next line, press Return, then Control-D. Choose one input form per search. Run greenbubbles help --all for the full command list, greenbubbles messages list --help for help with a specific command, or greenbubbles version (also -v or --version) to check the installed version.

Replace "Alice" with a chat's nickname, remark, or alias. chats find matches partial names without reading messages. messages list and messages search accept names too; if a name matches several chats, the command shows choices so you can use an exact ID.

messages list and messages search print JSON Lines: a header, then one line per message with who sent it, whether it was you, the local time, and the text. messages list includes local paths for photos, videos, and files when they can be opened. Search results name the chat; use messages list to get attachment paths.

• Chat names: --conversation accepts an exact ID, nickname, remark, or alias. Exact names take priority over partial matches, ignoring case. If several chats match, the error lists their IDs so you can choose one.
• **Conversati