aradotso 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 initagain
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
initwithsudoon 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
initagain
"Database decryption failed"
Solution:
- WeChat version changed — run
initagain 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
sessionscommand to see exact chat names - Try searching with partial name using
contacts --query
new-messages Returns Everything
Solution:
- Delete
~/.wechat-cli/last_check.jsonto 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
- Python ≥ 3.10 (for pip installation)
- Node.js (for npm installation)
Platform Support:
| Platform | Status | Notes |
|---|---|---|
| macOS (Apple Silicon) | ✅ | Bundled arm64 binary |
| macOS (Intel) | ✅ | Supported via pip/source |
| Windows | ✅ | Reads Weixin.exe process memory |
| Linux | ✅ | Reads /proc/pid/mem, requires root |
How It Works
- Key Extraction: Scans WeChat process memory for SQLCipher encryption keys
- Decryption: Transparent AES-256-CBC decryption with page-level caching
- Query: Local SQLite queries on decrypted database
- Privacy: All data stays local — no network access, no cloud transmission
Read-only: This tool only reads locally stored data, never sends or modifies messages.
Quick Reference
# Setup
sudo wechat-cli init
# Common queries (JSON output)
wechat-cli sessions --limit 10
wechat-cli history "Alice" --limit 50
wechat-cli search "keyword" --chat "Group"
wechat-cli contacts --detail "Bob"
wechat-cli unread
wechat-cli new-messages
# Human-readable output
wechat-cli sessions --format text
wechat-cli history "Alice" --format text --limit 20
wechat-cli stats "Group" --format text
# Export & analysis
wechat-cli export "Chat" --format markdown --output file.md
wechat-cli stats "Group"
wechat-cli members "Group"
wechat-cli favorites --query "search term"
# Filters
--limit N --offset N
--start-time "YYYY-MM-DD" --end-time "YYYY-MM-DD"
--type text|image|voice|video|file|link|call|system
--format json|text