greenbubbles README

The project's README from github.com/bojieli/greenbubbles. As one markdown file: README.md.

GreenBubbles icon

GreenBubbles

Enable your AI agents to access your WeChat history in real time.
Mac CLI + skills for agents. Local storage only.

Install · Get your key · CLI usage · Use with an agent · Docs · Database format · Contribute

CI Release License: MIT Platform: macOS 14+ Status: research alpha

GreenBubbles queries WeChat’s original encrypted databases locally and returns live results to your agent, without maintaining an exported chat database. A separate optional path creates an encrypted backup you can unlock and query later without WeChat.

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:

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

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.

Build from source

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

The account key is captured into a private file on your Mac. That key and the database file’s salt derive the key used for local read-only access to WeChat’s original database.

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"
Command When to use it
greenbubbles messages list --conversation "Alice" Read the newest messages in one chat, including available attachment paths.
greenbubbles chats Browse a page of chats and their IDs.
greenbubbles messages search --query "keyword" Search message text across your chats.
greenbubbles messages search --conversation "Alice" --query "keyword" Search message text within one chat.
greenbubbles chats rank Find your most active conversations, ranked by how many messages you sent, with one-on-one chats first.
greenbubbles chats find "Alice" Find a chat by nickname, remark, alias, or ID; partial names work.
greenbubbles contacts list --details Browse contacts with their nicknames, remarks, and aliases.
greenbubbles message get --conversation <conversation-id> --message <message-id> Fetch one message using its ID from --json output.
greenbubbles source status Check database access and storage sizes without reading message text.

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.

Details: CLI reference.

Prefer a window? Open the app and choose Browse Live or Snapshot…. It reads the same WeChat data as the command-line tool.

You can let a coding agent you already pay for do the reading and writing: Codex, Claude Code, OpenCode, Kimi Code, Gemini CLI, or Grok Build. If you're signed in with a subscription, this usually costs nothing extra.

GreenBubbles gives the agent a skill: a Markdown file of instructions, with helper files next to it. Nothing needs to be installed. With Homebrew, this prints where the skill is:

echo "$(brew --prefix greenbubbles)/libexec/skills/greenbubbles-personal-memory/SKILL.md"

Then tell your agent something like:

Read the GreenBubbles personal-memory SKILL.md at that path. Organize my conversations in the recent month into Markdown notes.

If you use the ZIP or a source checkout, the skill is at skills/greenbubbles-personal-memory/SKILL.md; keep the files around it in place. To have your agent find the skill automatically in future sessions, copy it into the agent's skills folder:

# Replace codex with claude, opencode, kimi, gemini, or grok.
python3 "$(brew --prefix greenbubbles)/libexec/scripts/install-skills.py" --agent codex

The agent reads messages through GreenBubbles and writes notes on your Mac. If the agent uses a cloud model, the messages it reads go to that provider. Never paste your database key or recovery phrase into a prompt.

More help: agent skills guide.

Use the built-in summarizer (optional)

If you don't use a coding agent, GreenBubbles can send chosen chats to Google's Gemini and save a cited summary as memory.md and memory.json. Run it with ai-summarize-direct.

This needs your own GEMINI_API_KEY and is billed by Google separately. Only conversations you have explicitly allowed in a policy file are sent. Each run writes a fresh summary; to keep improving the same set of notes over time, use a coding agent instead.

Setup steps: built-in summarizer guide.

Choose your next step

I want to… Read
Set up and start browsing User guide
Have my agent write notes from my chats Agent skills
Understand how the notes are organized Personal memory
Give an AI access to only some chats Give an AI access to only some chats
Back up and restore my history Recoverable snapshots
Fix a problem FAQ and known limitations
Understand the design Architecture and threat model

Everything else is in the documentation index.

Privacy

Everything GreenBubbles reads or writes stays on your Mac: WeChat's databases, your key file, backups, and notes. There is no telemetry or update check.

Message text leaves your Mac only when you choose a cloud AI:

A coding agent that can run commands has the same access to your files as you do. The skill tells it what to do but cannot restrict it. Notes and backups contain private information, so protect them as carefully as WeChat's own data. Details: PRIVACY.md.

Status

GreenBubbles is a research alpha for technical users reading their own data. WeChat changes its private formats; when GreenBubbles meets data it can't read, it says so instead of guessing. Public builds cannot send messages. See known limitations.

Contributing

Contributions are welcome, especially:

See CONTRIBUTING.md to get started. Use synthetic examples in reports and tests; leave out real messages, databases, keys, and account paths. Report security issues through SECURITY.md.

License

MIT — see LICENSE. Binary releases include third-party notices.

GreenBubbles is an independent project, not affiliated with or endorsed by Tencent. WeChat and other product names are trademarks of their respective owners.

greenbubbles (bojieli/greenbubbles)

Searching Database…

383 ·GitHub
Greenbubbles
Что это?GreenBubbles — это инструмент командной строки для Mac (с опциональным приложением и навыком для агента), который читает вашу историю переписки WeChat прямо из файлов баз данных, которые WeChat уже хранит на вашем Mac, позволяя просматривать её, искать, создавать резервные копии или просить агента для кодинга превратить выбранные переписки в заметки Markdown со ссылками на источники.
Это инструмент CLI или приложение с GUI?Это прежде всего инструмент CLI, устанавливаемый через Homebrew, но также доступно приложение macOS (DMG), подписанное Developer ID и нотаризованное, с окнами Browse Live и Snapshot, которые читают те же данные WeChat.
Как его установить и начать читать свои переписки?Установите CLI через Homebrew или скачайте приложение DMG из раздела Releases, затем запустите одноразовую настройку ключа, которая извлекает ключ расшифровки WeChat из запущенного приложения WeChat; после этого команды вроде greenbubbles chats работают без дополнительных флагов.
Готово ли это к надёжному повседневному использованию?Нет, это помечено как исследовательская альфа для технических пользователей: WeChat меняет свои закрытые форматы баз данных, поэтому GreenBubbles честно сообщает об этом вместо догадок, когда встречает данные, которые не может прочитать, а публичные сборки не умеют отправлять сообщения.
Работает ли это и на Mac с Intel?Нет, требуется Mac с Apple silicon и macOS 14 или новее.
Куда на самом деле попадают мои данные WeChat?Всё, что GreenBubbles читает или записывает, остаётся на вашем Mac, без телеметрии и проверки обновлений; текст сообщений покидает ваш компьютер, только если вы решите, что его прочитает облачный ИИ-агент или встроенный суммаризатор Gemini.
Как это работает с Claude Code или Codex?GreenBubbles поставляет файл SKILL.md в формате Markdown со вспомогательными файлами; вы направляете на него своего агента для кодинга и просите организовать выбранные переписки в заметки Markdown со ссылками на источники, ничего дополнительно устанавливать не нужно.
Что такое встроенный суммаризатор?Опциональная функция, запускаемая через ai-summarize-direct, которая отправляет в Google Gemini (используя ваш собственный API-ключ) только те чаты, что вы явно разрешили в файле политик, и записывает memory.md/memory.json со ссылками на источники.
Как защищены резервные копии?Резервные копии зашифрованы и защищены фразой восстановления из 24 слов, так что вы сможете открыть историю переписки позже даже без установленного WeChat.
Почему настройке нужен доступ администратора?Одноразовое извлечение ключа копирует ключ расшифровки из запущенного приложения WeChat и переподписывает вашу копию WeChat, что требует прав администратора.
What are similar projects?wechat-intelligence-hub, WeChatBridge, ambient-context, graph-memory-starter, chubbyskills, RemoveMacAI, leviathan, course2md
Which topics is it in?personal-knowledge-management, privacy-tools, backup, note-taking, wechat, agent-memory, memory, macos-app, homebrew, knowledge-base, apple-silicon, cli-tool
Creator
bojieli
Size
3.3 MB
Stars
383
Updated
CommitOct 01
Age
1mo
Commits · 90 Days