💬 wechat-cli

Query your local WeChat data from the command line — built for AI agents.

Chat history · contacts · sessions · favorites · stats · export — decrypted locally, served as JSON, zero network calls in the query path.

Quickstart · Commands · Fork Changes · Privacy · When NOT to Use · 中文

Fork notice — this is anthonyhann's fork of 苍何's wechat-cli (upstream: freestylefly/wechat-cli · npm @canghe_ai/wechat-cli). The fork adds WeChat 4.x cross-platform key acquisition and a hardened read-only authorization boundary (workspace v0.3.0, source-only, not yet published to npm/PyPI). See What this fork changes.

---

😮‍💨 Sound familiar?

• Your AI agent is blind to your WeChat — years of chats, contacts and favorites sit in an encrypted local database it can't read.
• Exporting chat history means uploading it to some cloud service you don't trust.
• Key-extraction tools silently read process memory, re-sign the WeChat app, or save keys without asking.

wechat-cli turns the local SQLCipher database into 11 read-only query commands + init that any LLM agent can call — and in this fork, every privileged step (memory reads, helper builds, key saves) requires an explicit flag.

Talking to your agent, it feels like this:

You:   帮我看看微信有没有未读消息
Agent: $ wechat-cli unread
       [{"chat": "项目组", "unread": 3}, {"chat": "张三", "unread": 1}]

You:   在项目群里搜一下关于「截止日期」的消息
Agent: $ wechat-cli search "截止日期" --chat "项目组"

🚀 Quickstart

1 · Install

# Published upstream release (v0.2.x):
npm install -g @canghe_ai/wechat-cli

# This fork's v0.3.0 (source, Python ≥ 3.10):
git clone https://github.com/anthonyhann/wechat-cli.git
cd wechat-cli && python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e .

2 · Initialize (read-only by default — verifies existing keys, never extracts without explicit flags)

wechat-cli init
wechat-cli keys check        # read-only coverage diagnostics

3 · Query

wechat-cli sessions                     # recent sessions
wechat-cli history "张三" --limit 20     # chat history
wechat-cli search "deadline" --chat "项目组"

On macOS, grant your terminal Full Disk Access (System Settings → Privacy & Security) so it can read the WeChat data directory. Key extraction from memory is off by default and requires explicit --allow-memory-read — see platform matrix.

📦 The 12 Commands

Command	What it returns
sessions	Recent conversations (default 20, --limit, --format text)
history	Chat messages — --limit/--offset/--start-time/--end-time/--type
search	Message search — global or --chat-scoped, 10 type filters
contacts	Contact search & detail (nickname, remark, wxid, signature)
members	Group member list
stats	Per-chat stats: totals, type distribution, top-10 speakers, 24h activity
export	Chat export to Markdown / plain text (--output)
favorites	WeChat favorites — --type text/image/article/card/video
unread	Unread sessions
new-messages	Incremental new messages since last check (state in ~/.wechat-cli/)
init	Setup — read-only by default; explicit --keys import with HMAC validation + .bak backup
keys	Key lifecycle: check · prepare · probe · extract (each gated by explicit flags)

Default output is structured JSON, designed for LLM tool-calling; --format text for humans. Full per-command options: 中文命令详解.

🔀 What This Fork Changes

One commit on top of upstream v0.2.4 — WeChat 4.x key acquisition + authorization hardening (workspace v0.3.0):

Area	Upstream v0.2.4	This fork (v0.3.0)
Key commands	init only	New keys group: check (read-only) · prepare (explicit helper build) · probe (diagnostics only) · extract (gated by --allow-memory-read; saved only with --save)
init	Auto-extract flow	Read-only by default; explicit --keys import validated by DB-page HMAC, existing files backed up to .bak, --force required to replace
macOS	Auto re-sign WeChat on task_for_pid failure	Signs only this tool's own new helper bundle; never re-signs, restarts, or modifies WeChat; never touches SIP
Windows	Memory scan	New config-scan path with legacy scan as fallback
Linux	Read-only scan	Keeps read-only scan; adds explicit GDB capture (x86_64 only, login-time breakpoint, PBKDF2-HMAC-SHA512 256k rounds)
Frida	Optional dependency	Refused at runtime — isolated-copy write routing unverified
Cache	Shared	Namespaced per DB-dir + keyset, WAL header/frame checksum validation, atomic publish, private temp files
Versions	Mixed	Unified 0.3.0 across Python, npm, and 5 platform packages
Tests	—	99 unit tests (synthetic/mock DB & memory fixtures)

Verified on a real machine (2026-10-14, macOS 26.6 arm64, WeChat 4.1.15): helper signed and probed, extraction 22/22 database HMAC passes, ~72 s for post-restart extraction, WeChat binary & existing configs untouched. Limits: the test machine's WeChat was ad-hoc signed with get-task-allow — officially-signed binaries may still be denied by the OS; Windows/Linux were not machine-verified that round.

📊 The Numbers

Metric	Value
Commands	12 top-level (+ 4 keys subcommands)
Unit tests	99 (python -m unittest discover -s tests -v)
Message-type filters	10 (text / image / voice / video / sticker / location / link / file / call / system)
Runtime dependencies	3 (click, pycryptodome, zstandard)
npm platform packages	5 (darwin-arm64/x64, linux-arm64/x64, win32-x64)
Real-machine verification	22/22 database first-page HMAC passes (2026-10-14)
Python	≥ 3.10

🔐 Privacy & Data Flow

Verified against the source:

• Zero network calls in the package — no requests/urllib/httpx/socket connections anywhere in wechat_cli/. Querying and decryption are fully local.
• Read-only by design: no send / modify / delete commands exist. The tool does write its own config, keys (only with --save), backups, decrypt cache (~/.cache/wechat-cli/), state and export files.
• Keys are sensitive files: saved with 600 permissions in 700 directories (icacls hardening on Windows); never printed, never silently persisted.
• Memory access is opt-in: --allow-memory-read for probe/extract, --allow-helper-build for helper compilation, --save for persistence. No auto re-signing, no SIP changes, no WeChat restarts.
• AI integration caveat: the CLI never uploads anything — but once you paste output into an AI tool, that data leaves your machine. Review what you forward.

💻 Platform Matrix

Platform	Key methods	Notes
macOS (Apple Silicon / Intel)	auto / config	Own signed helper (build via keys prepare --allow-helper-build, needs Xcode CLT); task_for_pid may still be denied by SIP/AMFI — not auto-bypassed
Windows (64-bit)	auto / config / legacy	config scans configuration; auto falls back to legacy scan
Linux	auto / legacy / gdb	auto = legacy read of /proc/<pid>/mem; explicit gdb capture is x86_64 only

Historical test environment: macOS 26.3.1+ and WeChat Mac 4.1.x — not a min/max compatibility guarantee. --method frida is listed but refuses to run.

⚠️ When NOT to Use It

• You want to send messages or automate WeChat actions. This CLI is query-only — no send, no modify, no delete, no automation.
• Your data isn't yours. Only use it on data you're authorized to access; you are responsible for complying with local law and WeChat's terms.
• You need a guarantee it works on every WeChat version. Key extraction depends on WeChat's memory layout; new releases can break it. Run wechat-cli keys check first.
• You want a finished, published v0.3.0. The workspace is 0.3.0 but not yet published to npm/PyPI — the published npm package is upstream's 0.2.x. Known issue: strict WAL validation may refuse stale-generation tail frames and fail some queries (fix pending).
• You're on Linux ARM64 and need GDB capture. Not supported (parameter layout); ARM64 package availability ≠ verified extraction.

🙏 Credits

• Upstream project: 苍何's wechat-cli (npm @canghe_ai/wechat-cli) — the CLI, query commands, and npm distribution are theirs. If this tool helps you, star upstream; watch this fork for WeChat 4.x key-acquisition updates.
• Core decryption & parsing: wechat-decrypt
• WeChat 4.x key references: wechat4mac (signing probe & config-candidate validation), wcdb-key-tool (Linux capture & derivation); studied wechat4-macos-frida-export's Gadget approach (not enabled here).
• Fork changes (v0.3.0): anthonyhann

License

Apache-2.0 — inherited from upstream. © 苍何 (upstream) · fork modifications © anthonyhann.