WAIT — Stale — last commit 3y ago

• 16 active contributors
• MIT licensed
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 75% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

ItChat is a Python library that provides a complete API for WeChat's personal account (non-official), enabling developers to build bots, automation, and CLI tools without reverse-engineering the WeChat protocol. It abstracts WeChat's message handling, contact management, and login flow into a simple decorator-based API where 30 lines of code can create a functional chatbot. Modular package structure: itchat/ is the main module with components/ subdirectory containing four core handlers (contact.py, login.py, messages.py, register.py), plus config.py and content.py for configuration and message types. docs/ contains Markdown tutorials and API reference. No monorepo; single-package design.

Python developers building WeChat bots, personal automation tools, or CLI clients who need programmatic access to WeChat personal accounts without using the official (limited) public API. Primarily Chinese developers and automation enthusiasts.

The project is functional but aging: 122K lines of Python code with comprehensive documentation (docs/intro and docs/tutorial folders), but no visible CI/CD pipeline in the file list and no test directory present. The README indicates active use cases and examples, but the lack of test infrastructure and unknown commit recency suggests it may not be actively maintained for newer WeChat versions.

High risk for production use: this library reverse-engineers WeChat's undocumented protocol, which WeChat actively discourages and may break without notice. No automated tests or CI pipeline visible, single-maintainer project (littlecodersh), and no dependency lock file shown—making version stability uncertain. WeChat periodically updates their protocol, likely breaking this library.

Unable to determine from provided file list—no git log, PR list, or issue tracker data included. The project structure suggests it may be in maintenance mode rather than active feature development.

git clone https://github.com/littlecodersh/ItChat.git
cd ItChat
pip install -e .

Daily commands: No 'run' in traditional sense; it's a library imported into user scripts. Example usage from README: python -c "import itchat; itchat.auto_login(); itchat.send('Hello', toUserName='filehelper')". For development: no setup.py or Makefile visible, likely uses pip install -e.

• itchat/__init__.py — Main entry point exposing the public API (auto_login, send, msg_register, run); every contributor must understand how the library's surface API is exported
• itchat/core.py — Core orchestrator managing login, message handling, and event loop; central to understanding how the WeChat session lifecycle works
• itchat/components/login.py — Handles WeChat QR-code login flow and session management; critical authentication path that all users traverse
• itchat/components/messages.py — Message receiving, parsing, and dispatch logic; fundamental to the message-handling pipeline
• itchat/components/register.py — Decorator-based message handler registration system; enables the core API pattern shown in README examples
• itchat/components/contact.py — Contact/user management and caching; powers friend, group, and public account discovery
• itchat/config.py — Configuration constants and API endpoint definitions for WeChat protocol; required reference for all network calls

• Login (itchat/components/login.py) (HTTP (requests), file I/O for hotreload storage) — Manages QR-code generation, user scanning, and session token acquisition from WeChat
  • Failure mode: QR expired, network timeout, account banned → auto_login() returns False; user must troubleshoot manually
• Messages (itchat/components/messages.py) — undefined

Add a new message handler type

1. Define a new message type constant in itchat/content.py (e.g., EMOJI = 47) (itchat/content.py)
2. Add parsing logic in itchat/components/messages.py to handle the new content type in the message reception loop (itchat/components/messages.py)
3. Register a handler using @itchat.msg_register(itchat.content.EMOJI) in your script (itchat/__init__.py)

Add a new WeChat API method

1. Add the endpoint URL and parameters to itchat/config.py in the appropriate configuration group (itchat/config.py)
2. Implement the method in itchat/core.py or a component module, using utils.post() or utils.get() to make HTTP calls (itchat/core.py)
3. Export the method from itchat/init.py to make it available to users (itchat/__init__.py)

Persist custom user data across sessions

1. Create a new storage module or extend itchat/storage/templates.py with your data class (itchat/storage/templates.py)
2. Modify itchat/components/hotreload.py to serialize and deserialize your custom data on login/logout (itchat/components/hotreload.py)
3. Access persisted data via a module-level variable or property exposed in itchat/init.py (itchat/__init__.py)

Add a custom message filter or preprocessor

1. Implement filter logic in itchat/components/register.py, extending the msg_register decorator to support additional criteria (itchat/components/register.py)
2. Update itchat/components/messages.py to apply the filter before invoking handlers (itchat/components/messages.py)
3. Export the enhanced decorator from itchat/init.py with usage examples in the docstring (itchat/__init__.py)

• Python 2/3 compatible — Reaches broader user base; WeChat integration often runs on legacy systems
• Requests library (via utils.py) — Standard HTTP client for WeChat API communication; abstracts SSL and session management
• Polling-based message reception — WeChat personal account API does not support WebSocket; polling is the only mechanism available
• Decorator-based handler registration — Provides intuitive, Pythonic API matching Flask patterns; users recognize the paradigm immediately
• In-memory message queue — Low-latency, single-process design; avoids external dependencies for simple bots

• Polling every 1–2s instead of push/webhook

  • Why: WeChat personal API has no push capability; callback servers require external infrastructure
  • Consequence: Higher latency (~1–2s), more bandwidth, CPU overhead; simplicity for standalone scripts

• Single-threaded blocking loop in core.py

  • Why: Simplicity and no race conditions; fits typical bot use case (handle one message at a time)
  • Consequence: Cannot process multiple concurrent messages; long-running handlers block the loop (mitigated via threading in advanced usage)

• Unencrypted local session file storage (hotreload)

  • Why: Convenience for personal use; avoids re-authentication on restart
  • Consequence: Security risk if home directory compromised; fine for personal accounts

• No built-in rate limiting or retry logic

  • Why: Keeps API minimal; users can wrap send() calls with decorators
  • Consequence: Risk of WeChat account throttling or bans if naive user sends bulk messages

• Production-grade multi-user bot platform (designed for personal account, not enterprise)
• Official WeChat API support (reverse-engineered personal protocol; unofficial and fragile)
• Real-time guaranteed message delivery (polling inherently lossy)
• End-to-end encryption (WeChat handles this; ItChat is a thin client)
• Mobile app distribution (Python-only, server/desktop use only)

WeChat protocol changes break this library without warning—no version pinning or compatibility layer. The library requires valid WeChat credentials and may trigger account blocks if WeChat detects automated access. QR code login (auto_login) may fail silently if WeChat server is unavailable. File downloads via msg.download() depend on undocumented endpoints. No built-in rate limiting, risking account suspension. The hotReload feature (session persistence) stores tokens unencrypted locally.

• WeChat Protocol Reverse-Engineering — ItChat's core capability—all network calls decode undocumented WeChat endpoints. Understanding this explains why breaking changes happen and why you cannot rely on this for production use.
• Decorator-Based Message Routing — The @itchat.msg_register pattern enables lightweight handler registration by message type; critical pattern for writing ItChat bots. Similar to Flask's @app.route.
• Dictionary-Attribute Duality — ItChat objects (Message, User, ChatRoom) support both msg['FromUserName'] and msg.fromUserName access patterns. Requires understanding Python descriptor protocol and getattr override.
• QR Code Authentication Flow — WeChat's login is QR-code-based, not password-based. ItChat must render/display QR codes and poll for scan status. Understanding this clarifies why auto_login() is blocking and enables debugging auth failures.
• Session Persistence via Hot Reload — ItChat's hotReload feature stores login tokens locally to skip QR scans on restart. Requires understanding cookie/token lifecycle and expiration in web authentication.
• Message Type Enumerations — WeChat distinguishes 10+ message types (TEXT, PICTURE, RECORDING, VIDEO, ATTACHMENT, CARD, SHARING, FRIENDS, etc.). Handlers must filter by type using constants from itchat/content.py.
• Group Chat @ Mentions — Group messages require detecting @mentions (msg.isAt) and knowing the actual sender (msg.actualNickName vs msg.senderNickName). Logic differs from personal 1:1 chat; critical for group bots.

• wechatpy/wechatpy — Alternative Python WeChat API library with official public account support; handles both personal and business accounts with more test coverage
• littlecodersh/itchatmp — Sister project by same author for WeChat official accounts (公众号); shares similar decorator-based API design as ItChat
• liuwons/wxBot — Older WeChat bot library in Python; predecessor/inspiration for protocol reverse-engineering approach in ItChat
• youfou/wxpy — Modern successor to ItChat with better protocol updates and community maintenance; recommended if ItChat breaks with new WeChat versions
• aiosns/aiosns — Async WeChat notification service; complements ItChat for high-throughput message scenarios

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.

Add comprehensive unit tests for itchat/components/login.py

The login component is critical for the library's functionality, but there are no visible test files in the repo structure. Adding unit tests for login.py would cover QR code generation, credential validation, session management, and error handling - essential for ensuring reliability across WeChat API changes.

• [ ] Create tests/test_login.py with test cases for auto_login() and manual login flows
• [ ] Add mocking for WeChat API endpoints to avoid actual login requirements during testing
• [ ] Test credential persistence and session validation in itchat/storage/
• [ ] Add integration test for the login retry mechanism and timeout handling
• [ ] Document test setup in docs/intro/login.md

Add GitHub Actions CI workflow for automated testing on Python 2.7 and 3.5+

The repo displays badges for py27 and py35 support but has no CI configuration visible. With .github/ directory already present, adding a GitHub Actions workflow would automatically test PRs against both Python versions, catch regressions, and validate dependency compatibility (especially critical given mkdocs==0.16.0 is pinned).

• [ ] Create .github/workflows/test.yml with matrix testing for Python 2.7, 3.5, 3.6, 3.7
• [ ] Add steps to install dependencies from setup.py and requirements.txt
• [ ] Run pytest against itchat/ to catch import and runtime errors
• [ ] Add linting check (flake8) for code quality validation
• [ ] Update README.md with CI badge and test status

Create API documentation for itchat/components/messages.py in docs/

The file structure shows docs/intro/messages.md exists but docs/api.md is empty or incomplete. messages.py handles critical message type routing and filtering, but there's no detailed API reference. Adding comprehensive documentation with examples for message handling, filtering decorators, and message types would reduce support burden.

• [ ] Expand docs/api.md with a 'Messages' section documenting @itchat.msg_register() decorator
• [ ] Document all content types available in itchat/content.py with examples
• [ ] Add code examples in docs/intro/messages.md for filtering by sender, type, and content
• [ ] Document the message object structure and accessible properties
• [ ] Add troubleshooting section for common message handling issues

• Add unit tests for itchat/components/contact.py search_friends() method—currently untested, with no test/ directory visible. Start by mocking WeChat API responses and testing the four search modes (self, by UserName, by name, by exact attributes).
• Document the message object structure and available properties in docs/intro/messages.md with a reference table—README only shows msg.text and msg.type. Extract and list all properties from itchat/content.py class definitions (e.g., FromUserName, ToUserName, CreateTime).
• Add error handling examples to docs/tutorial/tutorial1.md for common failures: login timeouts, invalid toUserName in send(), network disconnects during run(). Currently no error handling documentation.

The ItChat codebase presents moderate security concerns. The most critical issue is the severely outdated mkdocs dependency (v0.16.0 from 2016) which contains multiple known vulnerabilities. Additionally, the WeChat personal account authentication mechanism lacks visible secure credential storage, and message handling lacks input validation. The project would benefit from dependency updates, implementation of secure credential management practices, comprehensive input validation, and security hardening of API communications. Regular security audits and dependency scanning are recommended.

• High · Outdated Dependency - mkdocs — docs/requirements.txt (mkdocs==0.16.0). The project uses mkdocs==0.16.0, which was released in 2016 and is severely outdated. This version contains multiple known security vulnerabilities and does not receive security patches. The current version of mkdocs is significantly newer and includes critical security fixes. Fix: Update mkdocs to the latest stable version (currently 1.5.x or later). Run: pip install --upgrade mkdocs. Review the changelog for breaking changes and test thoroughly before deploying.
• High · WeChat Credential Management Risk — itchat/components/login.py, itchat/core.py. The codebase implements WeChat personal account authentication (auto_login) without visible secure credential storage mechanisms. WeChat session tokens and authentication data could potentially be stored insecurely on disk or in memory without proper encryption or secure handling. Fix: Implement secure credential storage using OS-level keychains (keyring library), encrypt stored credentials at rest, use environment variables for sensitive configuration, and ensure session tokens are handled securely in memory with appropriate cleanup.
• Medium · Missing Input Validation in Message Handling — itchat/components/messages.py, itchat/storage/messagequeue.py. The message handling system (itchat/components/messages.py) may process user-supplied data without adequate validation. This could lead to injection attacks or unexpected behavior when processing malicious message content. Fix: Implement comprehensive input validation for all message types. Sanitize and validate message content, sender information, and metadata. Use allowlisting for expected message formats rather than blocklisting.
• Medium · Potential Insecure Deserialization — itchat/storage/templates.py, itchat/components/contact.py. The codebase handles WeChat protocol messages and contact data that may involve deserialization operations. Without proper safeguards, this could be vulnerable to deserialization attacks if untrusted data is processed. Fix: Avoid using pickle or unsafe deserialization methods. Implement strict schema validation for all incoming data. Use safe serialization formats (JSON) with strict type checking.
• Low · Lack of Security Headers in Documentation — docs/bootstrap/. The documentation website (docs/bootstrap) serves static content but the configuration does not show security headers implementation (CSP, X-Frame-Options, etc.). Fix: When serving documentation, implement security headers including Content-Security-Policy, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and Strict-Transport-Security.
• Low · Missing HTTPS Enforcement — itchat/core.py, itchat/components/. The project communicates with WeChat servers and handles user authentication. No visible enforcement of HTTPS-only connections or certificate pinning for API communications. Fix: Enforce HTTPS for all API communications with WeChat. Implement certificate pinning for critical connections. Use secure session configurations and validate SSL/TLS certificates properly.

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

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

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/littlecodersh/ItChat 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.

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

What it runs against: a local clone of littlecodersh/ItChat — 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 littlecodersh/ItChat | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 984 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of littlecodersh/ItChat. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/littlecodersh/ItChat.git
#   cd ItChat
#
# 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 littlecodersh/ItChat and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "itchat/__init__.py" \\
  && ok "itchat/__init__.py" \\
  || miss "missing critical file: itchat/__init__.py"
test -f "itchat/core.py" \\
  && ok "itchat/core.py" \\
  || miss "missing critical file: itchat/core.py"
test -f "itchat/components/login.py" \\
  && ok "itchat/components/login.py" \\
  || miss "missing critical file: itchat/components/login.py"
test -f "itchat/components/messages.py" \\
  && ok "itchat/components/messages.py" \\
  || miss "missing critical file: itchat/components/messages.py"
test -f "itchat/components/register.py" \\
  && ok "itchat/components/register.py" \\
  || miss "missing critical file: itchat/components/register.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 984 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~954d)"
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/littlecodersh/ItChat"
  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).

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