bojieli/greenbubbles

What it solves

GreenBubbles allows users to access and search their own WeChat chat history on macOS without needing to export data manually. It specifically enables AI agents (like Claude Code or Codex) to read this history in real time to create structured notes, private wikis, or summaries of a user's life based on their conversations.

How it works

The tool operates as a Mac CLI and optional app that reads WeChat's original encrypted databases stored locally on the machine. It requires a one-time setup to capture the account's encryption key from the running WeChat app (requiring administrator access). Once the key is acquired, GreenBubbles can query the live database directly, returning results in JSON Lines format for humans or AI agents. It also provides "skills" (Markdown instruction files) that guide coding agents on how to use the CLI to retrieve and organize chat data.

Who it’s for

Technical macOS users (Apple silicon, macOS 14+) who want to programmatically access their WeChat history for personal knowledge management or to enhance their AI agents with personal context.

Highlights

• Real-time Access: Reads live databases directly, eliminating the need for manual exports or maintaining duplicate copies.
• Agent Integration: Provides pre-defined skills for popular coding agents to turn conversations into cited Markdown notes.
• Local-First Privacy: All reading, searching, and storage happen locally on the Mac; data only leaves the device if the user explicitly uses a cloud-based AI provider.
• Encrypted Backups: Supports creating encrypted snapshots of chat history protected by a 24-word recovery phrase.
• Comprehensive CLI: Includes tools to list chats, search messages, rank active conversations, and redact personal details.