GreenBubbles reads your own WeChat history on your Mac and lets you choose which parts, if any, an AI gets to see. Start with the repository README. Use this page to find the right guide next.
| I want to… | Read |
|---|---|
| Install the command-line tool or check a download | CLI releases and Homebrew |
| Set up the key GreenBubbles needs | Key setup guide |
| Install and browse my history | User guide |
| Have my coding agent write notes from my chats | Agent skills |
| Understand how those notes are organized | Personal memory |
| Give an AI access to only some chats | Give an AI access to only some chats, then AI tool boundary |
| Keep a backup that works without WeChat | Recoverable snapshots |
| Fix something that isn't working | FAQ |
| Know what it can't do before installing | Known limitations and threat model |
| Understand how it works | Architecture, then storage format |
| Understand WeChat files and message formats | Database format |
| Check a performance claim | Measurements |
| Compare it with WeChat export tools | Comparison |
| Contribute | Contributing |
- User guide: first run, finding your WeChat data, browsing, and making and opening backups.
- FAQ: common questions, including the ones where the answer is "that's a real limitation."
- Command-line reference: every command, and how keys are passed to it safely.
- Query profiles: saved settings for reading a second account or a backup without retyping paths and keys.
- History browser: the Mac app, what it shows and stores, and what it deliberately can't do.
- Recoverable snapshots: encrypted backups, the 24 recovery phrase, changing how a backup is unlocked, and testing recovery.
- Key setup guide: copying the database key from your own WeChat app, checking it, and fixing problems.
- Agent skills: use GreenBubbles from the coding agent you already have (Claude Code, Codex, and others), including keeping notes up to date.
- Personal memory: how the agent turns your chats into a set of notes, one article per area of your life.
- Give an AI access to only some chats: answering one AI request at a time, giving an AI access limited to chats you choose, and the built-in Gemini summarizer.
- AI tool boundary: what an AI tool may ask for, and what it can never reach.
- AI memory integration: feeding cited messages into local memory and search systems.
- Connector API: the request and response format for programs that integrate with GreenBubbles.
- Architecture: why GreenBubbles reads WeChat's data in place instead of exporting all of it, with the measurements behind that choice.
- Database format: the live directory layout, table discovery, message fields, media, XML, and CLI normalization.
- Storage format: what WeChat 4.1 writes to disk, how much of it GreenBubbles understands, and how gaps are reported.
- Restoration specification: the full, lossless export format.
- Replica specification and replica operations: an optional encrypted local copy of your history that stays in sync with WeChat.
- Measurements: every performance number, with the machine, date, and method, and what it doesn't prove.
- Auditing: independently checking exports, replicas, backups, key captures, and the AI access log.
- Known limitations: everything GreenBubbles doesn't support or hasn't proven yet, in one place.
- Operational response plan: what to do if a key, a backup, or a Mac is compromised.
- Distribution inventory and public release checklist: third-party licenses and the checks every release must pass.
- Threat model: what GreenBubbles protects, from whom, and what it doesn't try to do.
- Action safety contract: the rules any action visible to other people would have to follow.
- Send adapter: the experimental message-sending code, and why public builds can't send.
- Roadmap: what's next, and what each step must prove first.
- Comparison: how GreenBubbles differs from WeChat export and forensic tools, including when those are the better choice.
archive/ keeps old plans, feasibility studies, and development
notes for the record. They may be out of date; read
its README before relying on anything there.