If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/BlueMatthew/WechatExporter shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Looks unmaintained — solo project with stale commits

• GPL-2.0 licensed
• ⚠ Stale — last commit 1y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live BlueMatthew/WechatExporter repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/BlueMatthew/WechatExporter.

What it runs against: a local clone of BlueMatthew/WechatExporter — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in BlueMatthew/WechatExporter | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 467 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of BlueMatthew/WechatExporter. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/BlueMatthew/WechatExporter.git
#   cd WechatExporter
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of BlueMatthew/WechatExporter and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "BlueMatthew/WechatExporter(\\.git)?\\b" \\
  && ok "origin remote is BlueMatthew/WechatExporter" \\
  || miss "origin remote is not BlueMatthew/WechatExporter (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "WechatExporter/core/Exporter.h" \\
  && ok "WechatExporter/core/Exporter.h" \\
  || miss "missing critical file: WechatExporter/core/Exporter.h"
test -f "WechatExporter/core/WechatParser.h" \\
  && ok "WechatExporter/core/WechatParser.h" \\
  || miss "missing critical file: WechatExporter/core/WechatParser.h"
test -f "WechatExporter/core/ITunesParser.h" \\
  && ok "WechatExporter/core/ITunesParser.h" \\
  || miss "missing critical file: WechatExporter/core/ITunesParser.h"
test -f "WechatExporter/core/ExportContext.h" \\
  && ok "WechatExporter/core/ExportContext.h" \\
  || miss "missing critical file: WechatExporter/core/ExportContext.h"
test -f "WechatExporter/ViewController.mm" \\
  && ok "WechatExporter/ViewController.mm" \\
  || miss "missing critical file: WechatExporter/ViewController.mm"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 467 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~437d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/BlueMatthew/WechatExporter"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

WechatExporter is a cross-platform C++ application that extracts and exports WeChat chat history from iTunes iOS device backups into HTML, PDF, or text formats. It parses encrypted WeChat databases (stored in SQLite within the iTunes backup), decrypts messages, and reconstructs group names and rich media metadata to generate browsable chat archives with support for lazy-loading, incremental exports, and search filtering. Monolithic Xcode project structure: WechatExporter/ contains the main application (AppDelegate.mm, AppConfiguration.mm) with platform-specific GUI (Objective-C++ Cocoa integration via Base.lproj/Main.storyboard for macOS), core export logic in C++, and HTML/PDF generation templates in res/templates/. Dependencies are statically linked; no separate engine/CLI boundary visible in this file tree.

iOS WeChat users who need to backup and archive their conversations for compliance, legal discovery, or personal record-keeping; the tool bridges the gap between WeChat's limited native export and the need for portable, searchable chat history archives that persist after message deletion.

Active and production-ready. The project is maintained with recent bug-fix releases (v1.8.0.10 as latest), has documented limitations (critical async-loading bug in versions pre-1.8.0.8 with patch tooling provided), and supports both Windows and macOS with official builds. However, testing infrastructure is not visible in the file list, and CI/CD setup is absent from the shared metadata.

Moderate risk: the codebase depends on 10+ external libraries (libxml2, libcurl, libsqlite3, protobuf, jsoncpp, lame, libplist, etc.) with no visible dependency lock or vulnerability scanning. Single maintainer (BlueMatthew) creates bus-factor risk. The project handles encrypted database decryption and iOS backup parsing—sensitive operations where subtle bugs in cryptographic handling (not visible in file list) could cause data loss or corruption.

Actively maintained with recent patch releases addressing async message loading bugs (v1.8.0.8–v1.8.0.10). The README warns of a critical bug in versions before 1.8.0.8 where incremental loading truncates messages, with distributed patch binaries (wxexpatch/wxexppatch) provided as workarounds. No ongoing feature development or major architectural changes are evident from the visible file structure.

1. Clone: git clone https://github.com/BlueMatthew/WechatExporter.git
2. Install dependencies: On macOS, use Homebrew: brew install libxml2 curl sqlite protobuf jsoncpp libplist (Windows requires manual SDK setup or pre-built binaries)
3. Open Xcode: open WechatExporter.xcworkspace
4. Build: xcodebuild -workspace WechatExporter.xcworkspace -scheme WechatExporter -configuration Release
5. Run: Built app appears in DerivedData; or download precompiled releases from GitHub releases page.

Daily commands: macOS: open WechatExporter.app (post-build) or run from Xcode (Product → Run). Windows (via precompiled binary): extract zip, launch WechatExporter.exe. Application is GUI-only; no CLI flag support visible. Requires iTunes backup directory path as input via file dialog.

• WechatExporter/core/Exporter.h — Core export orchestration interface; defines the main contract for all export operations and result notification.
• WechatExporter/core/WechatParser.h — Primary parser for WeChat message database; extracts raw messages, contacts, and metadata from iOS backups.
• WechatExporter/core/ITunesParser.h — iTunes backup parser; required for accessing encrypted WeChat database files from iOS device backups.
• WechatExporter/core/ExportContext.h — Export session context container; maintains state across async tasks and communicates progress to UI.
• WechatExporter/ViewController.mm — Main macOS UI controller; bridges user interactions (file selection, export triggers) to core export engine.
• WechatExporter/core/MessageParser.h — Message content parser; decodes protobuf and XML message payloads into structured chat history formats.
• WechatExporter/core/Template.h — HTML/PDF template engine; renders parsed messages into exportable HTML and PDF output formats.

Add Support for a New Message Type

1. Add message type enum value to WechatObjects.h (e.g., MESSAGE_TYPE_NEW_FORMAT = 999) (WechatExporter/core/WechatObjects.h)
2. Implement protobuf/XML parsing logic in MessageParser::parseMessage() to extract content (WechatExporter/core/MessageParser.cpp)
3. Add HTML rendering template in Template.cpp for the new message type (insertMessageHTML method) (WechatExporter/core/Template.cpp)
4. If media processing needed, add handler in Utils_* file (e.g., Utils_audio.cpp for audio types) (WechatExporter/core/Utils.h)

Add a New Export Output Format

1. Add format option to ExportOption.h (e.g., EXPORT_FORMAT_MARKDOWN = 4) (WechatExporter/core/ExportOption.h)
2. Create new template/converter class or extend Template.cpp with format-specific output methods (WechatExporter/core/Template.cpp)
3. Update Exporter.cpp to call format handler based on export option during buildExport() (WechatExporter/core/Exporter.cpp)
4. Add UI option in ViewController.mm export dialog to allow user format selection (WechatExporter/ViewController.mm)

Add Custom Message Filter Logic

1. Define filter criteria in ExportOption.h (e.g., date range, keyword, sender) (WechatExporter/core/ExportOption.h)
2. Implement filter predicate in Exporter::buildExport() where messages are iterated (WechatExporter/core/Exporter.cpp)
3. Add UI controls in ViewController.mm to expose filter options to user (WechatExporter/ViewController.mm)
4. Optionally store filter presets in AppConfiguration for persistence across sessions (WechatExporter/AppConfiguration.mm)

Support a New Media Type Download

1. Extend media URL extraction in MessageParser.cpp for the new media type (WechatExporter/core/MessageParser.cpp)
2. Add download task creation in DownloadPool.cpp and register handler in Downloader.cpp (WechatExporter/core/DownloadPool.cpp)
3. Add file format validation and caching logic in Downloader.cpp if needed (WechatExporter/core/Downloader.cpp)
4. Update Template.cpp to embed/reference the downloaded media in HTML output (WechatExporter/core/Template.cpp)

• C++ (core engine) — Cross-platform portability without heavy runtime dependencies; enables Windows/macOS support from single codebase
• Objective-C++ / Cocoa (macOS UI) — Native macOS integration for file dialogs, menu bar, and system-level iTunes backup access
• SQLite3 — WeChat on iOS stores messages in SQLite database; required for direct DB access and incremental export tracking
• Protobuf & XML parsing — WeChat message payloads are encoded as protobuf or XML; custom parsers avoid bloated protobuf compiler dependency
• libimobiledevice — Direct iOS device backup access without iTunes GUI; enables programmatic backup mounting and file extraction
• Chrome/Edge automation for PDF conversion — Avoids heavyweight PDF library; leverages browser's proven rendering and print-to-PDF capability

• Custom protobuf parser instead of official protoc compiler

  • Why: Reduces binary size and external dependencies; more portable
  • Consequence: Must manually update protobuf message definitions; maintenance burden when WeChat protocol changes

• Async/incremental loading with lazy pagination instead of monolithic single-file export

  • Why: Handles very large chat histories (100k+ messages) without memory exhaustion or browser hang
  • Consequence: Complex pagination logic; historical bug (v1.8.0.7) where later pages loaded fewer messages; requires patch distribution

• HTML templates with client-side filtering instead of

  • Why: undefined
  • Consequence: undefined

1. iTunes backup format complexity: Windows backups stored in C:\Users\[user]\AppData\Roaming\Apple Computer\MobileSync\Backup\; macOS path differs; code must abstract this (not visible in snippet).
2. WeChat database encryption: The app must decrypt encrypted SQLite databases; the encryption key derivation logic is not visible but is critical—any misstep causes data loss or corruption.
3. Template placeholder syntax: Documentation warns %%NAME%% placeholders must not be modified; any template edit that mangles these breaks export.
4. Async loading JavaScript bug (pre-1.8.0.8): Scroll-to-load mode truncates later pages; users on old versions need patch binary. The bug is patched but old HTML files remain broken unless re-exported.
5. No CI/CD visible: Releases are manual; Windows Visual C++ 2017 redistributable must be pre-installed by end users (mentioned in README); build-time dependency management opaque.
6. Single macOS-centric dev environment: Xcode project structure suggests primary development on macOS; Windows support may lag or have platform-specific bugs.

• iTunes Backup Structure & Manifest Database — WeChat chat history is encrypted inside a SQLite database within the iTunes backup; understanding the backup file layout (Manifest.db, domain/app-specific subdirectories) is essential for locating and extracting the correct database file without corrupting the backup.
• SQLite Database Decryption (SQLCipher) — WeChat stores encrypted chat messages in SQLCipher (encrypted SQLite); the decryption key is derived from the device UDID and iTunes backup format; incorrect key derivation silently fails or returns corrupted data.
• Protocol Buffers Message Deserialization — WeChat uses protobuf for compact message encoding (especially for rich media: images, videos, payments); deserializing these blobs correctly is necessary to extract message content and metadata.
• Lazy-Loading HTML Generation (Client-Side Pagination) — The exported HTML pages support three loading modes (all-at-once, async-on-open, scroll-to-load); understanding the difference (and the bug in scroll-mode truncation) helps debug export quality and contribute fixes.
• Incremental Export with Checkpoint Tracking — The tool can resume exports from the last message ID to avoid re-exporting; this requires persistent state management and correct timestamp ordering in SQLite queries; bugs here cause duplicate or missing messages.
• Silk-v3 Audio Codec Transcoding — WeChat voice messages are encoded in proprietary Silk-v3 format; the exporter uses the silk decoder to convert to PCM, then lame to encode to MP3 for browser compatibility; missing or buggy codec handling breaks audio export.
• Group Name Resolution from Encrypted Metadata — WeChat group chat names are stored in encrypted metadata blobs, not plaintext; the exporter reconstructs group names from protobuf-encoded contact lists and group membership records; incorrect parsing shows garbled or missing group names.

• stomakun/WechatExport-iOS — Direct predecessor: original Python/Objective-C WeChat exporter; this repo was forked and rewritten in C++ for cross-platform portability.
• libimobiledevice/libimobiledevice — Dependency used to access iOS device backups programmatically; understanding its API is crucial for extending device-direct export beyond iTunes backups.
• protocolbuffers/protobuf — Core dependency for deserializing WeChat protocol buffer messages stored in SQLite; modifying message parsing requires protobuf schema knowledge.
• collects/silk — Audio codec dependency: WeChat voice messages use Silk codec; this repo handles transcoding to MP3 via lame for export compatibility.
• junyanz/WechatMoments — Companion tool for exporting WeChat Moments (timeline posts); similar database extraction pattern but targets different message types.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Extract and document WechatExporter/core module architecture with unit tests

The core/ directory contains critical async/download infrastructure (AsyncExecutor, AsyncTask, DownloadPool, Downloader, ExportContext) but lacks any visible test coverage. Adding C++ unit tests for these core components would catch regressions in message loading and incremental export logic, which the README highlights as bug-prone areas (the v1.8.0.7 async loading bug mentioned). This is especially valuable given the complexity of async message pagination modes.

• [ ] Create tests/core/ directory structure
• [ ] Add unit tests for WechatExporter/core/AsyncExecutor.cpp covering task scheduling
• [ ] Add unit tests for WechatExporter/core/DownloadPool.cpp covering concurrent download limits
• [ ] Add unit tests for WechatExporter/core/ExportContext.h covering incremental export state management
• [ ] Integrate with Xcode test target in WechatExporter.xcodeproj/project.pbxproj

Add CI/CD workflow for building and validating macOS/Windows binaries

The repo has both macOS (.xcodeproj) and Windows build configurations but no GitHub Actions workflow to validate builds on pull requests. Given the complexity of supporting three export formats (Text, HTML, PDF) and platform-specific dependencies (libimobiledevice, libcurl, protobuf visible in LICENSES/), adding matrix builds would prevent regressions before release. The current patch mechanism (v1.8.0.8 patch_x64_win.zip / patch_x64_macos.zip) suggests post-release fixes are common and costly.

• [ ] Create .github/workflows/build-macos.yml to build WechatExporter.xcodeproj via xcodebuild
• [ ] Create .github/workflows/build-windows.yml for Windows binary compilation
• [ ] Add validation step to verify PDF conversion (Chrome/Edge automation) works in CI
• [ ] Document build prerequisites in README.md (Xcode version, Windows SDK, CocoaPods dependencies)
• [ ] Add artifact upload for successful builds to catch binary size/dependency regressions

Consolidate and document message type support matrix

The README mentions 'more message types export support' but WechatExporter/SessionDataSource.mm and ViewController.mm likely contain message parsing logic scattered across files without a clear inventory. Users need to know which message types (text, image, video, voice, link preview, location, etc.) are supported in each export format (Text/HTML/PDF). This documentation gap likely causes user confusion and unreported compatibility bugs.

• [ ] Audit WechatExporter/SessionDataSource.mm and WechatExporter/core/ for all message type handlers
• [ ] Create docs/MESSAGE_TYPES_SUPPORT.md with a matrix showing format × message type support
• [ ] Add inline code documentation to message parsing functions indicating which export formats support each type
• [ ] Remove or document the 'ViewController copy.mm' file (appears to be a duplicate or backup)
• [ ] Link support matrix from README.md in a new 'Features' section

• Add unit tests for AppConfiguration.mm database query functions: Core extraction logic currently has no visible test coverage; writing tests for WeChat database parsing (contact names, message timestamps, group metadata) would improve reliability and prevent regressions.
• Create a GitHub Actions CI workflow to auto-build releases for both Windows and macOS: Releases are currently manual; setting up build.yml would catch compile errors early, ensure reproducible builds, and eliminate the need for maintainer to manually distribute Visual C++ redistributable requirements.
• Expand the res/templates/ documentation with a template authoring guide: Users and contributors who want to customize output (e.g., add custom CSS, change date format, add dark mode) have no reference; a README in templates/ explaining each placeholder and showing example modifications would lower the bar for theme contributions.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.