Skip to content
Back to search

wechat-decrypt

SkillWorks with Claude CodeGitHub

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/freanocank--wechat-decrypt/badge.svg)](/listings/freanocank--wechat-decrypt)

HTML

<a href="/listings/freanocank--wechat-decrypt"><img src="/api/listings/freanocank--wechat-decrypt/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the repository, then run the setup script from its root.

macOS

bash setup.sh
.venv/bin/python scripts/common/doctor.py --json

Setup creates an isolated `.venv`, installs SQLCipher and Python dependencies, links the checkout at `$HOME/.agents/skills/wechat-decrypt`, and registers the `wechat` stdio MCP server with Codex. Missing keys and local caches are migrated from the legacy `$HOME/.codex/skills/wechat-decrypt` copy without overwriting current files. If the user-skill path points to another checkout, inspect it first and then run `bash setup.sh --upgrade`; the previous path is retained as a timestamped backup.

Core setup stays lightweight. Install the optional local voice stack only when needed with `bash setup.sh --with-voice`; this installs sizeable ML libraries but not the approximately 3 GB model.

First-time key extraction requires temporary ad-hoc signing:

sudo codesign --force --deep --sign - /Applications/WeChat.app
bash scripts/macos/extract_key.sh

The script closes WeChat, opens it through Frida, and waits for QR login. After the key is captured, reinstall WeChat from the App Store or official site to restore Tencent's signature. See [the macOS guide](references/macos.md) before extracting.

Windows

powershell -File setup.ps1
$Python = ".\.venv\Scripts\python.exe"
& $Python scripts\windows\extract_raw_key.py
& $Python scripts\windows\decrypt_all.py
& $Python scripts\common\doctor.py --json

The extractor closes WeChat and asks you to restart it manually from the visible desktop. `decrypt_all.py` then creates a private local plaintext mirror used by the read-only query layer. See [the Windows guide](references/windows.md).

For an existing user-skill junction that points elsewhere, use `powershell -File setup.ps1 -Upgrade`. Private files are copied only when missing; an existing `decrypted/` mirror is linked rather than duplicated.

Install the optional Windows voice stack with `powershell -File setup.ps1 -WithVoice`. Ordinary query and export do not require it.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 69 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: wechat-decrypt
  3. description: 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.
  4. ---
  5. # WeChat local history
  6. 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.
  7. ## Resolve the runtime
  8. Use the directory containing this `SKILL.md` as `SKILL_DIR`; never assume a fixed installation path.
  9. - macOS: prefer `$SKILL_DIR/.venv/bin/python`, otherwise `python3`.
  10. - Windows: prefer `$SKILL_DIR\.venv\Scripts\python.exe`, otherwise `python`.
  11. Before reading chat data, run the read-only diagnostic:
  12. ```bash
  13. "$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/common/doctor.py" --json
  14. ```
  15. On Windows, use the equivalent venv Python path. Interpret `fail` as blocking and `warn` as optional/degraded:
  16. - `key` or `database` failure: read the matching platform reference below.
  17. - `mcp` warning: use the CLI fallback now; run platform setup only when MCP registration is needed.
  18. - `voice-backend` warning: ordinary export works; install the optional platform voice stack only for transcription.
  19. - `voice-model` warning: ordinary export still works. Do not download the model without user approval.
  20. ## Route the request
  21. | Intent | Preferred action |
  22. |---|---|
  23. | List chats or groups | `wechat_list_chats` |
  24. | Read one chat | `wechat_read_chat` |
  25. | Search all chats | `wechat_search_messages` |
  26. | Review recent activity | `wechat_recent_messages` |
  27. | Summarize recent chats and action items | `wechat_chat_summary` |
  28. | Review pats, recalls, group changes, payments, or calls | `wechat_system_events`; filter with a stable code or Chinese label |
  29. | 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 |
  30. | Statistics, media, or a received document | CLI `stats`, `media`, or `openfile` |
  31. | Export history or transcribe voice | Read [references/export-transcription.md](references/export-transcription.md) |
  32. | Missing chats, a missing shard, or a corrupted database | Read [references/db-repair.md](references/db-repair.md) |
  33. | macOS setup, key failure, or WeChat update | Read [references/macos.md](references/macos.md) |
  34. | Windows setup, key failure, or WeChat update | Read [references/windows.md](references/windows.md) |
  35. MCP is a thin optional facade. If it is unavailable, use the same logic through `scripts/common/query.py` and request JSON:
  36. ```bash
  37. "$PYTHON" "$SKILL_DIR/scripts/common/query.py" list --json
  38. "$PYTHON" "$SKILL_DIR/scripts/common/query.py" read CONTACT -d 7 -n 50 --json
  39. "$PYTHON" "$SKILL_DIR/scripts/common/query.py" search KEYWORD -d 30 -n 50 --json
  40. "$PYTHON" "$SKILL_DIR/scripts/common/query.py" recent -d 3 -n 100 --json
  41. "$PYTHON" "$SKILL_DIR/scripts/common/query.py" summary -d 3 --json
  42. "$PYTHON" "$SKILL_DIR/scripts/common/query.py" events -e pat -d 30 -n 100 --json
  43. ```
  44. `[我]` 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.
  45. ## Operational invariants
  46. - Raw keys are 64 hexadecimal characters and are device-specific. macOS and Windows keys for the same account are not interchangeable.
  47. - macOS queries encrypted databases in place through SQLCipher, always read-only.
  48. - Windows first creates a local plaintext mirror under `decrypted/`, then queries it read-only. Treat that mirror as sensitive.
  49. - WeChat updates may invalidate extraction assumptions or require a new key. Run `doctor.py` before repeating extraction.
  50. - Voice transcription is offline after the model is cached. A first large-v3 download is about 3 GB and always requires user approval.
  51. - 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.
  52. - 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.
  53. - 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.
README.md · README · 159 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # wechat-decrypt
  2. [![tests](https://github.com/tzwkb/wechat-decrypt/actions/workflows/tests.yml/badge.svg)](https://github.com/tzwkb/wechat-decrypt/actions/workflows/tests.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  4. [![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
  5. English | [中文](README_ZH.md)
  6. A local-first [Codex Skill](https://developers.openai.com/codex/skills) for reading, searching, summarizing, exporting, and transcribing WeChat 4.x history on macOS and Windows. The command-line core also works without MCP; the bundled server provides an optional [Codex MCP](https://developers.openai.com/codex/mcp) facade.
  7. Use it only with local data you own or are authorized to access.
  8. ## What it does
  9. - Lists chats and resolves contact remarks, nicknames, aliases, and group names.
  10. - Reads, searches, summarizes, and measures messages across multiple database shards.
  11. - Classifies pats, recalls, group/friend changes, red packets, payments, calls, pins, and unknown system events.
  12. - Parses music, video links, Channels/live streams, mini programs, files, quotes, and unknown share cards while preserving titles, descriptions, sources, and URLs.
  13. - Exports a contact and date range without an artificial message-count cap.
  14. - Transcribes locally downloaded SILK voice messages with Whisper.
  15. - Diagnoses the installation without exposing raw keys.
  16. - Supports verified macOS and Windows key/decryption flows.
  17. ```text
  18. macOS: encrypted WeChat DB ── raw key ── SQLCipher read-only ─┐
  19. ├─ query.py ── CLI / MCP
  20. Windows: encrypted WeChat DB ── raw key ── private plaintext ──┘ └─ export / voice
  21. ```
  22. ## Quick start
  23. Clone the repository, then run the setup script from its root.
  24. ### macOS
  25. ```bash
  26. bash setup.sh
  27. .venv/bin/python scripts/common/doctor.py --json
  28. ```
  29. Setup creates an isolated `.venv`, installs SQLCipher and Python dependencies, links the checkout at `$HOME/.agents/skills/wechat-decrypt`, and registers the `wechat` stdio MCP server with Codex. Missing keys and local caches are migrated from the legacy `$HOME/.codex/skills/wechat-decrypt` copy without overwriting current files. If the user-skill path points to another checkout, inspect it first and then run `bash setup.sh --upgrade`; the previous path is retained as a timestamped backup.
  30. Core setup stays lightweight. Install the optional local voice stack only when needed with `bash setup.sh --with-voice`; this installs sizeable ML libraries but not the approximately 3 GB model.
  31. First-time key extraction requires temporary ad-hoc signing:
  32. ```bash
  33. sudo codesign --force --deep --sign - /Applications/WeChat.app
  34. bash scripts/macos/extract_key.sh
  35. ```
  36. The script closes WeChat, opens it through Frida, and waits for QR login. After the key is captured, reinstall WeChat from the App Store or official site to restore Tencent's signature. See [the macOS guide](references/macos.md) before extracting.
  37. ### Windows
  38. ```powershell
  39. powershell -File setup.ps1
  40. $Python = ".\.venv\Scripts\python.exe"
  41. & $Python scripts\windows\extract_raw_key.py
  42. & $Python scripts\windows\decrypt_all.py
  43. & $Python scripts\common\doctor.py --json
  44. ```
  45. The extractor closes WeChat and asks you to restart it manually from the visible desktop. `decrypt_all.py` then creates a private local plaintext mirror used by the read-only query layer. See [the Windows guide](references/windows.md).
  46. For an existing user-skill junction that points elsewhere, use `powershell -File setup.ps1 -Upgrade`. Private files are copied only when missing; an existing `decrypted/` mirror is linked rather than duplicated.
  47. Install the optional Windows voice stack with `powershell -File setup.ps1 -WithVoice`. Ordinary query and export do not require it.
  48. ## Query
  49. Agents should prefer `--json`; omit it for human-readable output.
  50. ```bash
  51. .venv/bin/python scripts/common/query.py list --json
  52. .venv/bin/python scripts/common/query.py list --limit 100 --offset 0 --json
  53. .venv/bin/python scripts/common/query.py read "Alice" -d 7 -n 50 --json
  54. .venv/bin/python scripts/common/query.py search "deadline" -d 30 -n 50 --json
  55. .venv/bin/python scripts/common/query.py recent -d 3 -n 100 --json
  56. .venv/bin/python scripts/common/query.py summary -d 3 --json
  57. .venv/bin/python scripts/common/query.py events -e pat -d 30 -n 100 --json
  58. ```
  59. Stable event filters are `pat`, `recall`, `group_join`, `group_remove`, `group_leave`, `group_rename`, `group_notice`, `group_admin`, `group_owner`, `group_disband`, `friend_added`, `red_packet`, `payment`, `call`, `chat_pinned`, and `system`. Chinese labels are also accepted.
  60. Type-49 share cards use the same parser in reads, searches, summaries, statistics, and exports. JSON output adds an `app` object with a stable kind, title, description, source, URL, and music/Channels/mini-program metadata. Unknown subtypes preserve common card fields and remain searchable through their local payload.
  61. Search decodes every compressed-text and type-49 candidate in bounded pages, so results are not limited to a fixed recent-card window. It does not create a persistent plaintext search index.
  62. The MCP server exposes the same core operations:
  63. | Tool | Purpose |
  64. |---|---|
  65. | `wechat_list_chats` | List conversations, 100 per page by default; continue with `offset` |
  66. | `wechat_read_chat` | Read one contact or group |
  67. | `wechat_search_messages` | Full-text search |
  68. | `wechat_recent_messages` | Review recent activity |
  69. | `wechat_chat_summary` | Structured recent-chat context |
  70. | `wechat_system_events` | Pats, recalls, group/friend changes, payments, calls, pins, and unknown events |
  71. ## Export and voice
  72. Ordinary text reads preserve the complete message and its line breaks. Query day
  73. windows must be positive integers; result limits accept 1–2000. Ambiguous contact
  74. names return candidates so you can select an exact wxid before reading or exporting.
  75. On Windows, set `WECHAT_DATA_ROOT` to the `xwechat_files` directory when storage has
  76. moved. Extraction, decryption and attachment discovery use that location. Decryption
  77. includes committed WAL pages and authenticates every encrypted page before replacing
  78. an existing snapshot; retry while WeChat is idle if the source changes during capture.
  79. See the [Windows guide](references/windows.md).
  80. Attachment export preserves relative source directories under `docs/`, `videos/`
  81. and `images/`, so same-named files survive. Windows attachments are read from the
  82. original account directory. Add `--with-media` to the chat exporter for a per-message
  83. image manifest and local image links. TXT shows relative paths; `.md` and `.html`
  84. outputs embed supported local images. Missing or encrypted originals retain an
  85. explicit status. See the [media-manifest guide](docs/media-manifest-proposal.md).
  86. ```bash
  87. .venv/bin/python scripts/common/export_chat.py "Alice" --year 2026 -o ~/Desktop/alice-2026.txt
  88. .venv/bin/python scripts/common/export_chat.py "Alice" --start 2026-01-01 --end 2026-06-30
  89. .venv/bin/python scripts/common/export_chat.py "Alice" --year 2026 --with-media --no-transcribe -o alice.html
  90. ```
  91. If the platform's Whisper large-v3 model is already cached, voice transcription is automatic. Otherwise ordinary export leaves `[Audio]` and does not download a model. Use `--transcribe` only after approving the approximately 3 GB first download, or `--no-transcribe` to disable transcription. See [the export and transcription guide](references/export-transcription.md).
  92. ## Security model
  93. - Query backends open databases read-only; SQLite writes are blocked with `query_only`.
  94. - Raw keys are validated, stored with private permissions, ignored by Git, and never echoed by extractors or diagnostics.
  95. - Plaintext databases, exports, derived-key caches, and voice caches use private permissions where supported.
  96. - The project does not upload chat data or use a cloud transcription service.
  97. - `key.txt`, `key_windows.txt`, `decrypted/`, `all_keys.json`, `contacts.json`, and `voice_cache.json` must never be committed.
  98. ## Development
  99. Unit tests use synthetic databases and require no personal WeChat data. The Windows extractor tests also execute its embedded JavaScript against synthetic memory using Node.js 22 or newer. Install test dependencies with `python3 -m pip install pytest pycryptodome 'mcp[cli]>=1,<2'`:
  100. ```bash
  101. python3 -m pytest -q
  102. python3 -m compileall -q appmsg.py config.py contacts.py crypto.py db.py message.py server.py scripts/common scripts/windows
  103. bash -n setup.sh scripts/macos/extract_key.sh
  104. .venv/bin/python -c "import asyncio, server; assert len(asyncio.run(server.mcp.list_tools())) == 6"
  105. ```
  106. Real-data checks are documented in [e2e/README.md](e2e/README.md). The Skill entrypoint is [SKILL.md](SKILL.md); platform and export details live under `references/` to keep agent context small.
  107. ## Contributors and acknowledgments
  108. Thanks to all [code contributors](https://github.com/tzwkb/wechat-decrypt/graphs/contributors) and everyone who helps through issue reports and design proposals. Contributions include:
  109. - [@Allen-CDA](https://github.com/Allen-CDA) diagnosed the Windows WeChat 4.1.12.55 key-extraction failure and provided multi-entry SHA-512 hook and process-detection improvement suggestions ([#1](https://github.com/tzwkb/wechat-decrypt/issues/1)).
  110. - [@Lee-Juntong](https://github.com/Lee-Juntong) contributed complete-text preservation, query validation and streaming, chat-list pagination, relocated Windows data and attachment paths, SQLCipher page authentication, and committed-WAL snapshots ([#7](https://github.com/tzwkb/wechat-decrypt/pull/7), [#8](https://github.com/tzwkb/wechat-decrypt/pull/8), [#9](https://github.com/tzwkb/wechat-decrypt/pull/9), [#10](https://github.com/tzwkb/wechat-decrypt/pull/10), [#11](https://github.com/tzwkb/wechat-decrypt/pull/11), [#12](https://github.com/tzwkb/wechat-decrypt/pull/12), [#13](https://github.com/tzwkb/wechat-decrypt/pull/13), [#14](https://github.com/tzwkb/wechat-decrypt/pull/14)).
  111. - [@ShiTan-677](https://github.com/ShiTan-677) contributed per-shard sender resolution, unambiguous contact selection, and collision-safe attachment export ([#3](https://github.com/tzwkb/wechat-decrypt/pull/3), [#4](https://github.com/tzwkb/wechat-decrypt/pull/4), [#5](https://github.com/tzwkb/wechat-decrypt/pull/5)), and proposed per-message local media manifests and transcript image links ([#6](https://github.com/tzwkb/wechat-decrypt/issues/6)).
  112. ## License
  113. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.