she-love-me: a WeChat chat-log analysis skill for AI coding agents

The problem she-love-me actually solves

Prompting a chat model with a wall of exported messages produces a different answer every time. The model summarises what it happens to notice, invents counts, and has no shared vocabulary for what it is describing. she-love-me attacks that by separating measurement from interpretation. The repository ships Python scripts that parse an export into a normalised per-contact directory, compute statistics over the whole log, and write both a terminal Markdown summary and an HTML report. The model is then asked to reason over numbers it did not produce.

The audience is narrow and specific. You need a WeChat 4.x installation on Windows or macOS, or a QQ account you can log into through NapCat and QQ Chat Exporter. You need to be comfortable in a terminal at least once, because the exporter setup is a command-line step even when an agent performs it. And you need to be the kind of person who wants a second opinion on a relationship badly enough to hand an AI agent your message history. The README frames the output around attachment types, Gottman-style repair attempts and Sternberg's three dimensions, so the intended reader is someone who wants a framework applied, not a verdict handed down.

How the pipeline moves from raw export to report

The data flow has four stages. First, a third-party exporter writes a JSON file to data/raw. Second, a converter script maps that vendor-specific shape onto the project's unified format and writes it under data/contacts/<contact>__<hash>/, which is why two different contacts never overwrite each other. Third, the statistics layer reads the normalised data and produces stats.json. Fourth, the report layer renders Markdown and HTML from those statistics, and the skill instructs the agent to sample a user-chosen time window rather than the entire history.

That sampling decision is the most interesting design choice in the repository. The README describes a three-layer architecture intended to avoid what it calls full-volume hallucination: statistics computed over everything, a user-selected analysis window, and layered sampling inside that window. The skill is supposed to recommend a range (one month, three months, six months, or everything) and show the message count for each option before the user picks. This is a real constraint, not a nicety. A multi-year WeChat history will not fit in a context window, and truncating it silently would bias every conclusion toward whatever the truncation kept.

Normalisation also handles a problem that breaks naive parsers: timestamps. The README states the scripts auto-detect seconds, milliseconds, microseconds, nanoseconds and common date strings, which matters because the supported exporters do not agree on a format. Emoji are stored separately, with messages.json holding only an emoji_ref and the metadata going to emojis.json.

Installing she-love-me and running a first analysis

Clone the repository and work from its root. The README is explicit that the terminal must be opened inside the she-love-me directory, and that the dependency install comes first.

git clone https://github.com/863401402/she-love-me
cd she-love-me
py -m pip install -r requirements.txt

requirements.txt pins only two packages, pycryptodome and zstandard, so the install is short. After that, the intended entry point is an agent, not a script. In Claude Code, Cursor, Copilot or Gemini CLI you invoke the skill with a slash command; in Codex you use a dollar-prefixed command.

/she-love-me

The skill then asks where the data comes from before doing anything else. If you are on Windows with WeChat 4.x, the agent runs the exporter setup on your behalf. The README documents the underlying calls so you can see what it is doing, including the provider selection and the export itself.

py scripts/setup_chat_exporter.py --provider auto --install
weflow-cli init
weflow-cli sessions
weflow-cli export "<联系人或 wxid>" json --output ".\data\raw"

The --provider auto flag is the important one: the installer tries weflow-cli first and falls back to CipherTalk when the environment is incompatible. Then the vendor JSON is converted into the project's layout, with the contact name and wxid supplied explicitly.

py scripts/convert_weflow_cli.py `
  --input ".\data\raw\<wxid>_messages.json" `
  --contact "<联系人显示名>" `
  --contact-id "<wxid>" `
  --output-dir data/contacts

What you should see afterwards is a contact directory under data/contacts, a stats.json for that contact, and a report you open in a browser from reports/. The README notes that the commands above are normally executed by the agent, and that they are documented mainly to explain what the agent did.

The exporter dependency is the real failure mode

she-love-me does not read WeChat's database itself. It delegates that to weflow-cli or CipherTalk, and the README says plainly that weflow-cli is a third-party project, is not part of this repository, and has not been independently security-audited by the maintainers. That sentence should shape how you evaluate the whole tool. The analysis code is MIT-licensed and readable. The component that touches your decrypted message database is neither.

The practical consequences are concrete. A WeChat version bump can break the exporter without anything changing in this repository. The README mentions that a fresh clone no longer attempts to download wechat-decrypt because it has been blocked, which is a small illustration of how quickly this layer moves. On the CipherTalk path there is a documented failure: if the npm CLI times out while fetching the key, the README warns against repeated re-logins and points to a headless adapter instead, run through the project's own diagnostic script with --scan-key --download-scanner. The diagnostic script is stated not to print database keys.

There is also a platform boundary. The WeChat path is documented for Windows and macOS with WeChat 4.x; Linux is not offered as a target for that route. QQ analysis requires NapCat plus the QCE plugin and a phone QR login, which is a separate setup entirely. If you cannot get either exporter working, the rest of the project has nothing to analyse. The traditional-deployment directory exists for people who would rather export messages.json themselves and hand it to any chat model, which sidesteps the agent integration but not the export problem.

How it differs from just prompting a model with your chat log

The obvious alternative is copying a conversation into a chat model and asking whether the other person is interested. The difference is where the numbers come from. In the manual approach, every count, percentage and trend the model mentions is generated by the model, and you have no way to check it. In she-love-me, the counts come from Python over the full export, and the model receives them as input. The README's own framing of this is that scores have a derivation source rather than being decided subjectively by the model.

The second difference is the sampling discipline. A manual prompt forces you to choose what to paste, usually by scrolling and guessing. The skill is designed to show you the message count behind each candidate window so the choice is informed. The third difference is output format: a terminal Markdown summary plus a shareable HTML report with Chart.js charts, rather than a chat reply you have to screenshot.

What the manual approach does better is portability. It works with any export format you can paste, needs no Python dependencies, no Node.js 18+, and no third-party binary touching your WeChat data. If your export is already a clean text file and you only want a one-off read, the skill's setup cost is not repaid.

Maintenance, licence and what upgrading costs you

The repository is MIT-licensed, which permits commercial and private use with the licence and copyright notice retained. That covers the code in this repository. It does not cover weflow-cli, CipherTalk, NapCat or QQ Chat Exporter, each of which carries its own licence and its own terms, and the README's statement that weflow-cli has not been audited here is a signal to check those projects separately before deploying anything on a machine holding real message data.

The last push to the default branch was on 2026-08-13. There are no retrieved releases, so there is no versioned upgrade path to follow; you track main. That has a direct cost: the exporter integration is the part most likely to need patching when an upstream tool changes, and there is no tagged version to pin against. Budget for re-running the exporter setup after any WeChat update, and expect the converter scripts under scripts/ to be the place where breakage surfaces. The dependency surface is small (two pinned packages in requirements.txt), so Python-side upgrades are cheap. The expensive upgrades are on the exporter side, and those are outside this project's control.

Editorial conclusion

Adopt she-love-me if you already have a working WeChat 4.x or QQ export pipeline and want a structured, locally generated report rather than freeform prompting. Skip it if you are on Linux for the WeChat path, if you cannot get a third-party exporter running, or if you need reproducible scoring you can audit. Before trusting a report, run py scripts/setup_chat_exporter.py --provider auto --install and confirm which exporter actually answered, then open the generated HTML in reports/ and check that the message counts match the conversation you selected.

Frequently asked questions

Official sources

1. 863401402/she-love-me on GitHub
2. Issues
3. License: MIT
4. README