FreePublished on GitHub

wechat-decrypt

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.

The English summary is being prepared. Showing the original description.

freanocank/wechat-decrypt

See how to install

Files included (128)

SKILL.md4.7 KB
.github/workflows/tests.yml1.4 KB
.gitignore205 B
agents/openai.yaml197 B
appmsg.py12.6 KB
config.py1.3 KB
contacts.example.json138 B
contacts.py4.3 KB
crypto.py2.4 KB
db.py10.7 KB
docs/2026-06-05-windows-keyextract-findings.md5.3 KB
docs/2026-06-05-windows-port-design.md6.1 KB
docs/2026-06-05-windows-port-plan.md28.7 KB
docs/2026-06-06-windows-raw-key-journey.md11.9 KB
docs/chat-list-pagination.md649 B
docs/media-manifest-proposal.md5.3 KB
docs/windows-data-root.md732 B
docs/windows-wal-snapshots.md990 B
e2e/check_consistency.py4.3 KB
e2e/README.md1.4 KB
e2e/test_e2e.py6.0 KB
LICENSE1.0 KB
message.py10.6 KB
NOTES.md1.1 KB
pyproject.toml375 B
README_ZH.md9.7 KB
README.md10.3 KB
references/db-repair.md4.6 KB
references/export-transcription.md3.2 KB
references/macos.md2.9 KB
references/windows.md4.4 KB
requirements-windows.txt120 B
scripts/common/crypto_backend.py1.1 KB
scripts/common/doctor.py11.7 KB
scripts/common/export_chat.py12.8 KB
scripts/common/export_media.py2.8 KB
scripts/common/media_manifest.py12.2 KB
scripts/common/migrate_private_state.py4.4 KB
scripts/common/query.py25.3 KB
scripts/common/read_doc.py7.3 KB
scripts/common/rebuild_from_factory.py5.6 KB
scripts/common/repair_factory.py4.6 KB
scripts/common/salvage_btree.py6.3 KB
scripts/common/salvage_export.py7.0 KB
scripts/common/salvage_rebuilt.py5.6 KB
scripts/common/sqlcipher_decrypt.py3.5 KB
scripts/common/transcribe_db.py5.7 KB
scripts/common/transcript_render.py2.2 KB
scripts/common/verify_key.py1.8 KB
scripts/common/voice_decode.py704 B
scripts/common/wal_snapshot.py4.0 KB
scripts/legacy/extract_key_frida.ps1792 B
scripts/legacy/extract_key.ps11.5 KB
scripts/legacy/find_key.ps17.4 KB
scripts/legacy/find_rawkey_follow.py2.2 KB
scripts/legacy/find_rawkey_v2.py2.5 KB
scripts/legacy/find_rawkey_via_salt.py2.3 KB
scripts/legacy/frida_aob.py1.3 KB
scripts/legacy/frida_attach_main.py2.8 KB
scripts/legacy/frida_attach_race.py2.1 KB
scripts/legacy/frida_brute_k1.py2.5 KB
scripts/legacy/frida_brute_rpc.py2.4 KB
scripts/legacy/frida_diag_read.py1.9 KB
scripts/legacy/frida_disasm.py1.3 KB
scripts/legacy/frida_entry_listen.py1.3 KB
scripts/legacy/frida_entry_verify_race.py2.7 KB
scripts/legacy/frida_entry_verify.py2.2 KB
scripts/legacy/frida_enum_dll.py1.1 KB
scripts/legacy/frida_enum_modules.py1.3 KB
scripts/legacy/frida_find_sha512.py1.3 KB
scripts/legacy/frida_find_via_kdfiter.py1.6 KB
scripts/legacy/frida_follow_ptr.py2.2 KB
scripts/legacy/frida_hook_alloc.py2.3 KB
scripts/legacy/frida_hook_bcrypt.py2.3 KB
scripts/legacy/frida_hook_entry_race.py2.3 KB
scripts/legacy/frida_hook_pbkdf2.py1.5 KB
scripts/legacy/frida_hook_sha512_v2.py1.5 KB
scripts/legacy/frida_hook_sha512.py2.1 KB
scripts/legacy/frida_hook_test.py1.1 KB
scripts/legacy/frida_memwatch_attach.py1.6 KB
scripts/legacy/frida_memwatch.py2.4 KB
scripts/legacy/frida_probe.py1.5 KB
scripts/legacy/frida_probe2.py1.9 KB
scripts/legacy/frida_sha512_entry_schtask.py2.2 KB
scripts/legacy/frida_sha512_race.py2.3 KB
scripts/legacy/frida_spawn_antidbg.py2.5 KB
scripts/legacy/frida_spawn_hook.py1.8 KB
scripts/legacy/frida_xref.py1.9 KB
scripts/legacy/hook_sqlite3_key_win.js1.0 KB
scripts/legacy/transcribe_voice.sh9.8 KB
scripts/legacy/transcribe.swift2.0 KB
scripts/legacy/verify_keys.py952 B
scripts/macos/extract_key.sh2.3 KB
scripts/macos/hook_pbkdf.js3.0 KB
scripts/windows/decrypt_all.py4.9 KB
scripts/windows/decrypt_read.py1.7 KB
scripts/windows/extract_raw_key.py10.0 KB
server.py2.5 KB
setup.ps14.5 KB
setup.sh5.0 KB
tests/conftest.py2.2 KB
tests/js/windows_extractor_harness.cjs4.1 KB
tests/test_app_messages.py9.7 KB
tests/test_chat_list_pages.py1.7 KB
tests/test_config.py812 B
tests/test_consistency_checker.py446 B
tests/test_contact_ambiguity.py3.8 KB
tests/test_crypto.py1.1 KB
tests/test_db_backend.py4.1 KB
tests/test_doctor.py2.7 KB
tests/test_export_safety.py722 B
tests/test_media_collisions.py1.8 KB
tests/test_media_manifest.py14.0 KB
tests/test_original_attachment_directory.py2.4 KB
tests/test_query_shards.py3.1 KB
tests/test_query_windows.py1.3 KB
tests/test_search_completeness.py2.8 KB
tests/test_search_streaming.py2.2 KB
tests/test_sender_identity.py3.7 KB
tests/test_sqlcipher_errors.py1.4 KB
tests/test_state_migration.py1.8 KB
tests/test_system_messages.py6.3 KB
tests/test_text_preservation.py458 B
tests/test_transcribe_backend.py2.4 KB
tests/test_wal_snapshot.py7.2 KB
tests/test_windows_data_root.py1.8 KB
tests/test_windows_extractor.py12.1 KB
tests/test_windows_page_authentication.py3.1 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

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.

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Report a problem with this skill

Install

Install with a command

npx skills add https://github.com/freanocank/wechat-decrypt --skill wechat-decrypt

Paste it into your terminal and run it (requires Node.js). You can choose which agents to install it for, such as Claude Code or Codex.

Ask your agent

Please install the following Agent Skill.
https://github.com/freanocank/wechat-decrypt

First review SKILL.md and the bundled files and confirm there is nothing suspicious (such as sending data externally or reading credentials). Then place it in ~/.claude/skills/wechat-decrypt/ for Claude Code, or ~/.agents/skills/wechat-decrypt/ for Codex.

Send this text to Claude Code or Codex as is. It checks the contents before installing.

View source on GitHub

Repository: freanocank/wechat-decrypt
Stars: 68
Forks: 34
Category: Writing & Fiction
License: MIT
Original language: English
Last updated: Oct 14, 2026

A skill is a set of instructions and scripts for an agent. cccskills does not guarantee that skills are safe. Review the contents before you install.