Chatlog Alpha: reading a local WeChat 4.x database, and what is left of it after a takedown

The repository is now a description, not a project

Chatlog Alpha is a local chat data reading and automation tool for WeChat 4.x. Its purpose is to discover local WeChat accounts, extract and manage keys, query the WCDB database read-only, decrypt media, and offer a unified entry point through a TUI, a web interface, a structured CLI, and a local HTTP JSON API.

What is left in the repository is not the code. The pinned notice at the top of the documentation explains why. Because of an infringement complaint from Tencent, the repository has stopped publishing source code, build artefacts, and historical releases, keeping only the project description. The project has moved to a third-party host, and the notice points there for the project status, update notifications, and the user subscription entry point, which is a Telegram channel.

The current state section repeats the same facts in more detail. The cloud repository keeps only the README and no longer publishes source code or binary build artefacts. The project has removed native text and image sending, the send debugging feature, the resident session injection, semantic retrieval, the time-series graph, and the experimental MCP functionality. The core direction that is retained is local data reading, database decryption, media processing, structured queries, message push, and local automation interfaces. And all status changes, version notes, and user notifications are published through the pinned Telegram subscription entry point rather than through the repository.

So the honest description of this project is that it is a well specified, carefully bounded local data tool whose implementation is no longer available from the place people look for it. The top level of the tree contains exactly one file, the README, which is consistent with that.

The capability list is a reading tool, not a messaging client

The set of current capabilities is what tells you what the tool actually does.

There is multi-process, multi-account discovery and switching. There is macOS database key and image key extraction. There is query access to conversations, messages, contacts, group chats, favourites, and the Moments feed. There is reading and decryption of images, video, voice, and attachments. There is database browsing, cross-database search, read-only SQL, and CSV and Excel export. There is message push over POST and over the Hermes Weixin and Hermes QQ channels. There is a self-describing CLI aimed at language models and a machine-readable HTTP API catalogue. And there are the TUI, the web console, and the structured `chatlog ops` and `chatlog api` interfaces.

The removed list is equally explicit, and it is worth reading as a design history. Gone are the `chatlog send` native text and image sending CLI, the `/api/v1/send-debug/*` native sending debug endpoints, the web console send debugging page and its static assets, the Frida based native sending scripts, the image upload agent, the welcome message, the resident session supervisor, and the semantic retrieval, embedding, MCP, and time-series graph experiment modules.

One clarification in the documentation matters for reading the removed list correctly: reading chat images, image key extraction, media decryption, and local preview remain part of the project's data reading capabilities and are not part of a native image sending feature. So the line the project drew was not between reading and writing media, it was between reading and sending messages.

The result is a read-and-export tool with a push channel, rather than the two-way client it once was. The project describes itself as an unofficial project with no affiliation, authorisation, or cooperative relationship with Tencent or WeChat, and it notes that the names and marks belong to their rights holders, and that users are responsible for following local law, software licences, and platform rules, and for the safety of their own local data and accounts.

Thirty-nine endpoints, and a deliberate split of privileged operations

The current HTTP catalogue contains 39 endpoints, and the table of categories is one of the more useful design documents in the project.

The system category has 4, covering health check, ping, the API catalogue, and OpenAPI. The chat category has 7, covering conversations, history, search, unread, group members, incremental messages, and statistics. The social category has 4, covering favourites, Moments notifications, the feed, and search. The address book category has 3, covering contacts, group chats, and OpenIM enterprise information. The database category has 6, covering databases, cross-database search, tables, data, read-only SQL, and cache. The media category has 6, covering images, video, voice, attachments, data files, and a Moments media proxy. And the push category has 9, covering push configuration, status, events, and the Hermes Weixin and QQ channels.

The totals are worth checking against the categories, because 4 plus 7 plus 4 plus 3 plus 6 plus 6 plus 9 is 39, which is a good sign that the summary and the implementation agree.

The single most important sentence about the catalogue is the one that follows it. The high-privilege operations, account selection, key extraction, database decryption, service lifecycle, and persistent configuration, are still managed by the local TUI or by the structured `chatlog ops` interface, not by the HTTP API.

That is a deliberate privilege separation rather than an omission. Key extraction and database decryption are the operations that would let a remote caller read everything, and keeping them out of the HTTP surface means a compromised web console, or a stray request from another program on the machine, cannot reach them. The HTTP API is for reading and querying; the TUI is for the sensitive operations.

The same logic appears in the runtime directory layout, with the default persistence root at `~/.chatlog`:

~/.chatlog/
├── chatlog.json
├── chatlog.pid
├── log/chatlog.log
├── cache/
└── workspaces/<account>/
    ├── runtime/hook.db
    └── cache/

The per-account workspace separation means two accounts on one machine do not share a runtime hook database or a cache, and the documentation notes that WeChat's own raw data directory is managed by WeChat and is not part of the Chatlog runtime root.

The security boundary section is the part to read first

Because the tool can read complete local chat data, the documentation states that it should be run only in a trusted local environment, and then lists the specific boundaries.

The HTTP service listens only on `localhost`, `127.0.0.0/8`, or `::1`, with a default address of `127.0.0.1:5030`. The database is connected in read-only and `query_only` mode. Configuration, keys, and the Hermes environment files use restricted file permissions. The Hermes token and secret are written only to the configuration and are not echoed back through the status interface. The Moments media proxy restricts private networks, loopback, link-local, user-info URLs, protocols, and response size. And the web console should not be exposed publicly through a reverse proxy, a port mapping, or a tunnel.

Each of those is a specific, checkable property rather than a general assurance, and a few of them are worth understanding individually.

Binding to loopback only is the first line of defence, and the choice of `127.0.0.0/8` rather than `127.0.0.1` is deliberate, so that a service on a different loopback address is still reachable locally while nothing on the physical network is. The `query_only` connection mode is the SQLite equivalent of a read-only mount, and it means that even a bug in the query layer cannot write to the WeChat database. And the media proxy restrictions exist because a media fetch that follows a URL from the database is a server-side request forgery vector, so the proxy has to refuse to reach internal addresses.

The rule about not echoing the Hermes token and secret through the status interface is the kind of detail that separates a considered implementation from a quick one, since a status endpoint is exactly the sort of thing that gets read by anything with access to the local machine.

The last rule, about the web console, is a statement that the tool's own developers could not enforce in software, so they state it as a requirement. A local HTTP service that is genuinely useful will be port-forwarded or tunnelled at some point, and this is the tool telling you that doing so puts a complete copy of someone's chat history on the public internet.

The contributor table survives the takedown, and it tells you about the project

One of the more revealing parts of the remaining documentation is the contributor acknowledgement table, and it comes with an unusual framing. The project thanks the contributors who previously submitted issue reproductions, measured data, and implementation proposals, and states that the contribution records are preserved even if the related functionality is later refactored or taken offline.

The entries are specific. One contributor is credited with dashboard and history query performance optimisation on large datasets. Another with OpenIM, webhooks, group chat backfill, cache refresh, and group chat mention parsing, across a run of pull requests. Another with a fix for truncated historical embedding responses, with the note that the related experimental functionality is now offline. Another with MCP, semantic retrieval, indexing, and message hook safety improvements, with the note that fixes that still apply are kept. Another with Windows process identification, an action CLI, and media and historical account support. Another with webhooks, the write-ahead log, file locks, and time range issue verification. And another with practical suggestions for image key scanning. Dependabot is credited with dependency updates and security fix suggestions.

Reading that list tells you several things about the project at its peak. It was actively developed, with a contributor base across Windows and macOS concerns, with an experimentation phase around semantic search and MCP that has since been removed, and with dependency automation in place.

It also tells you the shape of the work. The hard parts were the key extraction on macOS, the incremental message handling, the write-ahead log and file locking around the live WeChat database, and the caching needed to keep queries fast on a large dataset. The fact that the caching and the performance work on large datasets were a contribution rather than a core feature is a hint that a large WeChat database is slow to query without it.

And the closing note about preserving the records after the functionality is refactored or taken offline is the most human sentence in the document. It says that the work was real and that the people who did it should still be credited, which is a thing a project that has been forced to withdraw its source can still do.

Editorial conclusion

Chatlog Alpha is worth reading as a design document, because its endpoint catalogue and its security boundary section describe a careful piece of work on a genuinely hard problem, but it is not something you can install from the canonical source any more. Check three things before you rely on it: that you are willing to take code and binaries from a third-party host rather than the original repository, that your platform and WeChat version are covered, since the tool targets WeChat 4.x and macOS key extraction is what the documentation describes, and that the local HTTP API stays on loopback, because the project itself says the web console should not be exposed through a reverse proxy, a port mapping, or a tunnel.

Frequently asked questions

Official sources

1. Issues
2. README
3. teest114514/chatlog_alpha on GitHub