engineering / skill
Desktop Chat Reader
Read and search your own WhatsApp Desktop conversations on macOS with a read-only command-line skill.
At a glance
- Purpose
- Read and search your own WhatsApp Desktop conversations on macOS with a read-only command-line skill.
- Runs in
- Local agent with shell
- Operating systems
- macOS
- Needs
- Runtime: Python 3.11+, standard library only; Needs internet: No; Needs accounts or API keys beyond your agent: No
- Files and data
- Reads files: Yes; Writes files: Yes; Sends data to other services: No
- Tool type
- Skill
- Delivery
- Download from Skills Outpost
- Version
- 0.1.3
- ZIP SHA-256
- 776928dde9799627e5d147b9ac6c7add24113577c7ee5373a69227a08991315b
- Access
- Download from Skills Outpost
- Compatibility
- macOS only; Python 3.11 or newer, standard library only; WhatsApp Desktop installed and linked to a phone; an Agent Skills compatible harness that can run local Python commands. Default database: ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite. Select another local database with --db PATH or WHATSAPP_DB. Reads the ChatStorage.sqlite schema maintained by WhatsApp Desktop. Unsupported systems are refused before database I/O; supports committed WAL-only rows in a private snapshot.
- External costs
- None. No API key, external service or third-party dependency is required.
- Permissions
- macOS: read the selected database and adjacent WAL/SHM files; write only a private temporary copy under the system temp folder, deleted on normal exit, errors, Ctrl-C, SIGTERM and SIGHUP; SIGKILL or power loss may leave it in system temp; needs up to 1 GiB free space; no source writes. Full Disk Access may be required; symlinked source files are refused.
- Usage terms
- MIT license. Copyright 2026 Zero Width Lab. Use only conversations you are authorized to access. WhatsApp and WhatsApp Desktop are trademarks of WhatsApp LLC. macOS is a trademark of Apple Inc. Zero Width Lab is not affiliated with or endorsed by WhatsApp LLC. By Zero Width Lab (zerowidthlab.com)
Download from Skills Outpost
Get this version
FreeStatic source, format, secret-pattern and declaration checks with independent human source review.
- SHA-256 of the released ZIP
776928dde9799627e5d147b9ac6c7add24113577c7ee5373a69227a08991315b
The creator shows this version's package files publicly: anyone can read SKILL.md and the other files under Files, without an account. The ZIP download needs the version in your Library (how it works).
Sign in to add this version to your library and follow its creator for free.
Sign in to get freeA creator follow is free, not a paid membership. Your email is not shared with the creator.
Files
Version 0.1.3, shown publicly by its creator, exactly as in this version's ZIP. ZIP SHA-256: 776928dde9799627e5d147b9ac6c7add24113577c7ee5373a69227a08991315b. License: MIT (read it).
Each file has its own address. Read one as a web page at https://, or as JSON at https://; replace SKILL.md with any path below.
- manifest.json · 1.6 KiB
- LICENSE.txt · 1.0 KiB
- README.md · 6.3 KiB
- SETUP.md · 3.8 KiB
- SKILL.md · 7.7 KiB
- agents/whatsapp-analyst.md · 2.9 KiB
- references/schema.md · 9.8 KiB
- scripts/whatsapp_read.py · 32.4 KiB
- source-package.json · 2.7 KiB
- tests/test_hygiene.py · 4.0 KiB
- tests/test_whatsapp_read.py · 35.8 KiB
MIT
MIT LicenseCopyright (c) 2026 Zero Width Lab
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Version history
- Version 0.1.3 Current
No release notes for this version.
What it does
Desktop Chat Reader is a read-only command-line Agent Skill for reading and searching your own WhatsApp Desktop conversations on macOS. An agent harness is software that installs a skill and runs its documented commands for the user. It needs macOS, WhatsApp Desktop installed and linked to a phone, and Python 3.11 or newer. It is free under the MIT license. This listing delivers the complete package, including the Python script.Filters treat % and _ literally. Each message appears once, ordered by message date and then primary key. Chats appear most recently active first, excluding broadcast and status containers by default. The read and search commands support finite --days values at least 0 and integer --limit values from 1 to 1000. --groups-only and --dms-only are mutually exclusive. --text-only keeps rows with text that is non-empty after Python whitespace stripping, including media and system rows carrying text.
The contacts command lists the local JID-to-push-name directory rather than the user's address book; it can contain unsaved group participants and omit saved contacts. Sender labels use ME for the local account, the chat partner for inbound one-to-one messages, and the push-name directory with raw member JID fallback for groups. Resolution follows the documented best-effort chain. ZWAPROFILEPUSHNAME.ZPUSHNAME supplies the directory; ZWAMESSAGE.ZPUSHNAME is not a sender name.
Text output replaces each run of CR/LF characters with one space and removes U+0000–U+001F and U+007F–U+009F characters, including ESC; printable parts of escape sequences remain. JSON message text is trimmed at both ends. read appends a distinct trimmed caption to a non-empty body, or returns a media/type label with a caption or media basename when the body is empty. search returns only the trimmed body. JSON escapes U+0000–U+001F; U+007F, U+0080–U+009F and U+2028 are output as stored. It accesses the local database without a WhatsApp API. Text-mode search truncates the sanitized chat name to 28 characters and message text to 180 characters; JSON search has no such truncation.
Who it is for
macOS users with WhatsApp Desktop installed and linked to a phone who want a local, read-only way to inspect their own chats, search message text, or resolve group participants.Example tasks
List recent chats and filter them by a chat-name fragment.Read the last 100 messages from a selected one-to-one chat.
Read a group conversation using an exact placeholder JID such as 120000000000000001@g.us.
Search message bodies for a keyword over a chosen number of days and return a limited set of results.
List the local JID-to-push-name directory and filter it by a name fragment.
Request machine-readable JSON output for a supported command.
Use an alternate local ChatStorage.sqlite database with --db PATH or WHATSAPP_DB.
Getting started
SKILL.md and the scripts can be read without an account: SKILL.md at https://
python3 scripts/whatsapp_read.py chats --search team
python3 scripts/whatsapp_read.py read 120000000000000001@g.us --limit 100 --json
python3 scripts/whatsapp_read.py search keyword --days 30 --limit 50
python3 scripts/whatsapp_read.py contacts --search contact