wechat-cli-local-data

name wechat-cli-local-data description Query local WeChat chat history, contacts, sessions, and favorites from the command line with AI-first JSON output triggers ["check my wechat messages","search wechat chat history","export wechat conversation","get wechat unread messages","show wechat contacts","analyze wechat chat statistics","query my local wechat data","read wechat group messages"] WeChat CLI — Local Data Query Skill Skill by ara.so — Devtools Skills collection. A CLI tool to query your local WeChat data — chat history, contacts, sessions, favorites, and more. Designed for LLM integration with JSON output by default. All data stays on your machine; uses on-the-fly SQLCipher decryption. Installation npm (Recommended) npm install -g @canghe_ai/wechat-cli Currently ships with macOS arm64 binary. For other platforms, use pip: pip install wechat-cli Requires Python >= 3.10. From Source git clone https://github.com/freestylefly/wechat-cli.git cd wechat-cli pip install -e . Initial Setup Before using any commands, you must initialize the tool to extract WeChat encryption keys: # macOS/Linux (requires sudo for memory scanning) sudo wechat-cli init # Windows (run in elevated terminal) wechat-cli init Prerequisites: WeChat must be running On macOS: Terminal needs "Full Disk Access" (System Settings → Privacy & Security → Full Disk Access) This command: Auto-detects WeChat data directory Scans WeChat process memory for encryption keys Saves config to ~/.wechat-cli/ macOS: Handling task_for_pid failed Error If init fails with task_for_pid failed , the tool will automatically re-sign WeChat with required entitlements: Follow on-screen instructions Quit WeChat completely Reopen WeChat and log in Run sudo wechat-cli init again Manual re-signing (if auto-signing fails): sudo codesign --force --sign - --entitlements /dev/stdin /Applications/WeChat.app << 'EOF' <?xml version= "1.0" encoding= "UTF-8" ?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd" > <plist version= "1.0" > <dict> <key>com.apple.security.get-task-allow</key> < true /> </dict> </plist> EOF Core Commands Sessions — List Recent Chats # Get last 20 sessions (default, JSON output) wechat-cli sessions # Get last 10 sessions wechat-cli sessions -- limit 10 # Human-readable format wechat-cli sessions --format text JSON Output Structure: [ { "chat_name" : "Alice" , "last_message" : "See you tomorrow!" , "last_time" : "2026-04-15 18:30:45" , "unread_count" : 2 } ] History — Read Chat Messages # Last 50 messages with Alice (default) wechat-cli history "Alice" # Get 100 messages with pagination wechat-cli history "Alice" -- limit 100 --offset 50 # Filter by date range wechat-cli history "Team Group" --start-time "2026-04-01" --end-time "2026-04-03" # Filter by message type (text, image, voice, video, file, link, etc.) wechat-cli history "Alice" -- type link # Text format for reading wechat-cli history "Alice" --format text -- limit 20 JSON Output Structure: [ { "msg_id" : "123456" , "type" : "text" , "content" : "Hello!" , "sender" : "Alice" , "timestamp" : "2026-04-15 10:30:00" , "is_sender" : false } ] Search — Find Messages # Global search across all chats wechat-cli search "deadline" # Search in specific chat wechat-cli search "meeting notes" --chat "Work Team" # Search in multiple chats wechat-cli search "report" --chat "TeamA" --chat "TeamB" # Search with type filter (only files) wechat-cli search "proposal" -- type file # Date range search wechat-cli search "budget" --start-time "2026-04-01" --end-time "2026-04-30" Contacts — Search & Details # Search contacts by name wechat-cli contacts --query "Li" # Get contact details by name wechat-cli contacts --detail "Alice" # Get contact details by WeChat ID wechat-cli contacts --detail "wxid_abc123xyz" JSON Output (Detail): { "nickname" : "Alice" , "remark" : "Alice from Marketing" , "wechat_id" : "wxid_abc123xyz" , "bio" : "Always learning" , "avatar_url" : "https://..." , "account_type" : "personal" } Members — Group Member List # Get all members in a group (JSON) wechat-cli members "AI Research Group" # Text format for reading wechat-cli members "AI Research Group" --format text Stats — Chat Analytics # Get statistics for a chat wechat-cli stats "Team Group" # Stats for date range wechat-cli stats "Alice" --start-time "2026-04-01" --end-time "2026-04-03" # Text format with charts wechat-cli stats "Team Group" --format text Returns: Total message count Message type breakdown (text, image, file, etc.) Top 10 senders with message counts 24-hour activity distribution Export — Save Conversations # Export to markdown (stdout) wechat-cli export "Alice" --format markdown # Export to file wechat-cli export "Alice" --format txt --output alice_chat.txt # Export with filters wechat-cli export "Team Group" --start-time "2026-04-01" -- limit 1000 --format markdown --output team_april.md Supported formats: markdown , txt Favorites — WeChat Bookmarks # Get all favorites (recent first) wechat-cli favorites # Filter by type wechat-cli favorites -- type article # Search favorites wechat-cli favorites --query "machine learning" Types: text , image , article , card , video Unread — Unread Sessions # Get all unread sessions wechat-cli unread # Limit results wechat-cli unread -- limit 10 --format text New Messages — Incremental Updates # First run: returns unread + saves state wechat-cli new-messages # Subsequent runs: only new messages since last check wechat-cli new-messages # Text format for monitoring wechat-cli new-messages --format text State saved at ~/.wechat-cli/last_check.json . Delete to reset. Use Case: Perfect for automation/cron jobs to monitor new messages. AI Agent Integration WeChat CLI is designed for AI agent tool calls. All commands output JSON by default. Claude Code Integration Add to your project's CLAUDE.md : ## WeChat CLI You can use `wechat-cli` to query my local WeChat data. Common commands: - `wechat-cli sessions --limit 10` — list recent chats - `wechat-cli history "NAME" --limit 20 --format text` — read chat history - `wechat-cli search "KEYWORD" --chat "CHAT_NAME"` — search messages - `wechat-cli contacts --query "NAME"` — search contacts - `wechat-cli unread` — show unread sessions - `wechat-cli new-messages` — get messages since last check - `wechat-cli members "GROUP"` — list group members - `wechat-cli stats "CHAT" --format text` — chat statistics All commands output JSON by default. Add `--format text` for human-readable output. Example Agent Workflows Check unread messages: # Agent executes: wechat-cli unread --format text # Then summarizes results for user Search for project updates: # Agent executes: wechat-cli search "project status" --chat "Work Team" --start-time "2026-04-01" # Then extracts key information Analyze chat activity: # Agent executes: wechat-cli stats "AI Discussion Group" --format text # Then presents insights: most active hours, top contributors, etc. Export important conversation: # Agent executes: wechat-cli export "Client Meetings" --start-time "2026-04-01" --end-time "2026-04-07" --format markdown --output client_weekly.md # Then confirms export and location Message Type Filters Use with --type option on history and search commands: Type Description text Text messages image Images voice Voice messages video Videos sticker Stickers/emojis location Location shares link Links and app messages file File attachments call Voice/video calls system System messages Common Patterns Monitor New Messages in Script #!/bin/bash # Check for new messages every 5 minutes while true ; do NEW_MSGS=$(wechat-cli new-messages --format text) if [ -n " $NEW_MSGS " ]; then echo "New messages detected:" echo " $NEW_MSGS " # Send notification, etc. fi sleep 300 done Search Across Multiple Groups # Find deadline mentions in all project groups wechat-cli search "deadline" \ --chat "Project Alpha" \ --chat "Project Beta" \ --chat "Project Gamma" \ --format text Export Weekly Summaries # Export last week's messages from key chats START_DATE=$( date -d "7 days ago" +%Y-%m-%d) END_DATE=$( date +%Y-%m-%d) wechat-cli export "Team Sync" \ --start-time " $START_DATE " \ --end-time " $END_DATE " \ --format markdown \ --output "team_sync_weekly.md" Get Contact Details Before Messaging # Check if contact exists and get details CONTACT_INFO=$(wechat-cli contacts --detail "New Client" ) if [ $? -eq 0 ]; then echo "Contact found:" echo " $CONTACT_INFO " | jq '.nickname, .wechat_id' else echo "Contact not found" fi Configuration Configuration stored at ~/.wechat-cli/ : ~/.wechat-cli/ ├── config.json # WeChat data path, account info ├── keys.json # Encryption keys (auto-extracted) └── last_check.json # State for new-messages command config.json structure: { "data_dir" : "/Users/username/Library/Containers/com.tencent.xinWeChat/Data/Library/Application Support/com.tencent.xinWeChat/2.0b4.0.9/abc123" , "account_id" : "wxid_abc123xyz" } To reset: Delete ~/.wechat-cli/ and run init again. To switch accounts: Run init again and select different account. Troubleshooting "WeChat data directory not found" Solution: Ensure WeChat is running On macOS: Grant "Full Disk Access" to your terminal app Run init with sudo on macOS/Linux "Failed to extract encryption key" Solution: On macOS: Re-sign WeChat (tool will auto-attempt this) Ensure WeChat is logged in and active Try restarting WeChat and running init again "Database decryption failed" Solution: WeChat version changed — run init again to refresh keys Database corruption — check WeChat data directory permissions Empty Results for Valid Chat Name Solution: Use exact chat name (case-sensitive) For groups, use full group name as shown in WeChat Use sessions command to see exact chat names Try searching with partial name using contacts --query new-messages Returns Everything Solution: Delete ~/.wechat-cli/last_check.json to reset state First run after reset will return all unread messages Subsequent runs will only show new messages Permission Denied Errors macOS/Linux: # Use sudo for init sudo wechat-cli init # Regular commands don't need sudo wechat-cli sessions Windows: Run terminal as Administrator for init Regular commands can run without elevation System Requirements macOS ≥ 10.15 (Catalina) WeChat for Mac ≤ 4.1.8.100