Metadata-Version: 2.4
Name: macos-messages
Version: 0.2.0
Summary: Python library and CLI for reading macOS Messages.app data
Project-URL: Homepage, https://github.com/tpritc/macos-messages
Project-URL: Documentation, https://macos-messages.readthedocs.io
Project-URL: Issues, https://github.com/tpritc/macos-messages/issues
Author-email: Tom Pritchard <tom@tpritc.com>
License-Expression: MIT
License-File: LICENSE
Keywords: chat,imessage,macos,messages,rcs,sms,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.12
Requires-Dist: click>=8.0
Requires-Dist: phonenumbers>=8.13
Provides-Extra: docs
Requires-Dist: mkdocs-shadcn>=0.2; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
Description-Content-Type: text/markdown

<p align="center">
  <img src=".github/assets/header.png" alt="macos-messages viewing the last 4 messages from a contact named Nick Wangler. The messages are an excited discussion about a new AI product release." />
</p>

# macos-messages

macos-messages is a Python library and CLI for reading your macOS Messages.app data. It gives you quick, easy, read-only access to your iMessage and SMS history.

## Why would I want this?

I built this primarily so AI agents (like Claude running in a terminal) can read my messages on my behalf. When I'm working with an AI assistant and I say "find that restaurant recommendation someone texted me last week," I want it to actually be able to go look.

But it's useful for plenty of other things too:

- Search your messages for something you know someone sent you
- Export conversations for safekeeping
- Build tools that analyze your messaging patterns
- Pipe message data into other scripts

The key thing is that it's **read-only**. macos-messages can't send messages, modify anything, or access your Apple ID. It just reads what's already on your Mac.

## What it looks like

From the command line:

```bash
# List your conversations
messages chats

# Get messages from a chat
messages --chat 42
messages --chat "Mom"

# Get messages with a contact
messages --with "Mom"

# Search across everything
messages --search "dinner tomorrow"

# Include messages in "Unknown Senders" (excluded by default)
messages --search "discount" --include-unknown-senders

# List only unread messages
messages --unread

```

Or in Python:

```python
import messages

db = messages.get_db()

# Get your recent conversations
for chat in db.chats(limit=5):
    print(f"{chat.display_name}: {chat.message_count} messages")

# Read messages from a specific chat
for msg in db.messages(chat_id=42, limit=10):
    sender = "me" if msg.is_from_me else msg.sender.display_name
    print(f"{sender}: {msg.text}")
```

## Installation

```bash
uv tool install macos-messages
```

You'll need to grant Full Disk Access to your terminal app before this will work. See the [Permissions](https://macos-messages.readthedocs.io/en/latest/permissions/) guide for instructions.

## Documentation

Full documentation is available at [macos-messages.readthedocs.io](https://macos-messages.readthedocs.io/en/latest/), including:

- [Installation](https://macos-messages.readthedocs.io/en/latest/installation/) - Getting set up
- [Quickstart](https://macos-messages.readthedocs.io/en/latest/quickstart/) - Your first queries
- [CLI Reference](https://macos-messages.readthedocs.io/en/latest/cli/) - All the commands
- [Python Library](https://macos-messages.readthedocs.io/en/latest/library/) - Full API docs
- [Permissions](https://macos-messages.readthedocs.io/en/latest/permissions/) - macOS permissions explained

## Requirements

- macOS
- Python 3.12+
- Full Disk Access permission for your terminal

## Contributing

Bug reports and pull requests are welcome on [GitHub](https://github.com/tpritc/macos-messages). This project is intended to be a safe, welcoming space for collaboration.

## License

The library is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
