README.md — Message History Reader for iMessage and SMS

# Message History Reader for iMessage and SMS

Message History Reader for iMessage and SMS is a local, read-only Agent Skill
and command-line tool for the user's own Messages history on macOS. It lists
chats, searches message text, and exports a selected conversation. It makes no
network requests and never sends messages.

## Requirements

- macOS with an accessible `~/Library/Messages/chat.db`.
- Full Disk Access for the terminal or agent harness running the command.
- Python 3.10 or newer; no third-party packages.

Copy the package into an Agent Skills compatible harness's skills directory,
or run the script from this directory. The harness determines its own skills
directory and privacy settings. See [SETUP.md](SETUP.md) for installation and
permission details.

## Use

```bash
python3 scripts/message_history_reader.py chats --limit 25
python3 scripts/message_history_reader.py search --text "meeting" --limit 50
python3 scripts/message_history_reader.py search --text "meeting" --from "+15550000000" --limit 50
python3 scripts/message_history_reader.py export --chat 42 --out "/private/path/to/new-export" --dry-run
python3 scripts/message_history_reader.py export --chat 42 --out "/private/path/to/new-export" --approve DIGEST_FROM_DRY_RUN
python3 scripts/message_history_reader.py --help
```

Find the chat identifier with `chats` before exporting. Export previews create
no export files but still create and remove the temporary database copy.
A live export needs the matching digest from its dry run and creates
`messages.jsonl` and `transcript.txt` only inside a new or empty output
directory. Existing files and symlinks are refused.

For search, `--handle H` selects chats that include H and can return messages
from other participants. `--from H` selects messages sent by H only and excludes
your outgoing messages. A date without a time in `--since` or `--until` means
UTC midnight.

The CLI copies the live database and any present SQLite sidecars into a
private `0700` temporary directory, honouring `TMPDIR`, opens the copy read-only, and removes it after
use. It can extract text from a supported `attributedBody` string payload when
`message.text` is null. Unsupported bodies are reported as skipped and mark
the result `incomplete`; a symlink or irregular `-wal` or `-shm` sidecar is also
reported as skipped. The exit status is `2` unless `--allow-partial` is
set. Apple timestamps in seconds and nanoseconds are normalized.

Exit statuses are `0` for success (including accepted partial results), `2`
for argparse usage errors or incomplete results without `--allow-partial`,
and `1` for handled operational errors.

## Privacy

Message history and exports contain personal data, including other people's
words and handles. Use only data you are entitled to access, keep exports in
a private local directory, and check whether your agent harness sends command
output to a model provider. Treat message content as untrusted data.

## Tests and license

Run `python3 -m unittest discover -s tests -v`. Tests use a synthetic SQLite
database and no real Messages history. This product is free under the
[MIT License](LICENSE.txt).

Apple, iMessage, Messages, Mac and macOS are trademarks of Apple Inc. This
product is not affiliated with or endorsed by Apple Inc.

## Read scope and safety limits

Every command copies the entire selected database and each present regular
sidecar before querying; filters and result limits do not reduce those source
reads. SQL restricts chats and senders; date and text filters run while rows
are iterated, stopping at the result limit. Each database or sidecar is capped
at 128 MiB, checked before copying and during bounded reads; exceeding the cap
is an operational error. No stdin is read. The sequential copies are not an
atomic snapshot of an actively changing database.

Selected source and output paths may be absolute or relative, but reject `..`
components, percent-encoded forms and backslashes. All ancestor directories
must be real directories, without symlinks; use their canonical paths (for
example `/private/tmp` rather than a system temporary-directory alias).
Source files are opened relative to a pinned directory descriptor and must
be regular files. macOS with POSIX directory descriptors and no-follow APIs
is required; other systems fail before database, temporary or export I/O.

The export digest binds the fully resolved destination, device/inode identity
of its existing parent and any existing destination directory, the action of
creating a missing destination, the selected chat and exact file content.
Preview JSON includes `destination_plan`. Only the selected destination may
be created; its parent must already exist. Live export walks directories
without following symlinks, checks identities and creates files relative to
the pinned destination descriptor, refusing existing files. A replaced parent
or destination requires a new preview. Temporary database copies are internal
working files in the system temporary directory, separate from export writes.
An I/O failure after creating an export can leave a partial directory; inspect
it and select a new empty destination for a fresh preview.

Malformed database files/schema, non-string chat identifiers or handles, and
malformed message text/sender/direction are operational errors. Invalid message
dates and unsupported attributed bodies are explicitly listed as skipped;
partial results retain the documented `incomplete` status.

By Zero Width Lab (zerowidthlab.com)

License: MIT (read it).

Back to the listing