freanocankfreanocank/wechat-decrypt/SKILL.md

wechat-decrypt

Skill67 starsChanged 53 days agoMITView on GitHub

Read, search, summarize, export, and transcribe a user's own local WeChat 4.x history on macOS or Windows; diagnose setup and re-extract the device key after a WeChat update. Use for WeChat messages, chats, contacts, and local archives. Do not use for remote accounts or devices the user is not authorized to access.

2 other projects use a version of this.

Adopted by

Most recently taken up by

tzwkb/wechat-decryptword for word, first seen Sep 22, 2026
ludwighb/claude_skillstheir own version, first seen Apr 13, 2026

Other versions2 projects use a version of this.
Word for word · 1
tzwkb/wechat-decrypt★ 82100% same
Edited · 0
None found.
Wrote their own version · 1
ludwighb/claude_skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Use the directory containing this SKILL.md as SKILL_DIR.
line 12
Distinctive:
Before reading chat data, run the read-only diagnostic:
line 17

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

WeChat local history

Operate only on local WeChat data the user is authorized to access. Keep keys, decrypted databases, voice caches, and exports local. Never print a raw key or include one in chat, logs, commands, or reports.

Resolve the runtime

Use the directory containing this SKILL.md as SKILL_DIR; never assume a fixed installation path.

macOS: prefer $SKILL_DIR/.venv/bin/python, otherwise python3.
Windows: prefer $SKILL_DIR\.venv\Scripts\python.exe, otherwise python.

Before reading chat data, run the read-only diagnostic:

"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/common/doctor.py" --json

On Windows, use the equivalent venv Python path. Interpret fail as blocking and warn as optional/degraded:

key or database failure: read the matching platform reference below.
mcp warning: use the CLI fallback now; run platform setup only when MCP registration is needed.
voice-backend warning: ordinary export works; install the optional platform voice stack only for transcription.
voice-model warning: ordinary export still works. Do not download the model without user approval.

Route the request

Intent	Preferred action
List chats or groups	`wechat_list_chats`
Read one chat	`wechat_read_chat`
Search all chats	`wechat_search_messages`
Review recent activity	`wechat_recent_messages`
Summarize recent chats and action items	`wechat_chat_summary`
Review pats, recalls, group changes, payments, or calls	`wechat_system_events`; filter with a stable code or Chinese label
Review shared music, videos, Channels, mini programs, files, or links	Use normal read/search/summary tools; inspect the structured `app` object in CLI JSON when exact metadata matters
Statistics, media, or a received document	CLI `stats`, `media`, or `openfile`
Export history or transcribe voice	Read references/export-transcription.md
Missing chats, a missing shard, or a corrupted database	Read references/db-repair.md
macOS setup, key failure, or WeChat update	Read references/macos.md
Windows setup, key failure, or WeChat update	Read references/windows.md

MCP is a thin optional facade. If it is unavailable, use the same logic through scripts/common/query.py and request JSON:

"$PYTHON" "$SKILL_DIR/scripts/common/query.py" list --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" read CONTACT -d 7 -n 50 --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" search KEYWORD -d 30 -n 50 --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" recent -d 3 -n 100 --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" summary -d 3 --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" events -e pat -d 30 -n 100 --json

[我] means the account owner; [对方] means the peer. If contact matching is ambiguous, show the candidates and ask the user to choose; do not guess. Keep time windows and limits proportional to the request, and do not dump full history unless explicitly requested.

Operational invariants

Raw keys are 64 hexadecimal characters and are device-specific. macOS and Windows keys for the same account are not interchangeable.
macOS queries encrypted databases in place through SQLCipher, always read-only.
Windows first creates a local plaintext mirror under decrypted/, then queries it read-only. Treat that mirror as sensitive.
WeChat updates may invalidate extraction assumptions or require a new key. Run doctor.py before repeating extraction.
Voice transcription is offline after the model is cached. A first large-v3 download is about 3 GB and always requires user approval.
Type-49 app messages are parsed locally. Preserve their structured app metadata when answering questions about titles, creators, sources, URLs, files, mini programs, or Channels; unknown subtypes may still contain useful fields.
Setup migrates only missing private files from legacy installs. Switching an existing user-skill link requires the explicit platform upgrade flag and leaves a recoverable backup.
A damaged shard is quarantined into <name>.db.factory/ and is usually recoverable page by page. Never repair a live database in place: rebuild into a copy, verify it, and back up before restoring anything.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free