reading-sms-messages ยท diff
git:20260127.4050ddc to git:20260201.d26a208
14 added, 62 removed. Audit A to A.
---
name: reading-sms-messages
description: Read SMS and iMessage from macOS Messages app. Use when getting 2FA codes, checking recent texts, or searching message history.
---
# SMS Reader
**Location**: `~/Library/Messages/chat.db` (macOS Messages database)
- **Tool**: `tools/sms_reader/__init__.py`
-
- ## Quick Usage
+ **CLI**: `python -m tools.sms_reader.cli`
- ```python
- from tools.sms_reader import get_2fa, get_recent_messages, search_messages, get_latest_2fa_code
+ ## Commands
+ ```bash
# Get 2FA code from last 5 minutes
- code = get_2fa(minutes=5)
- print(f"Code: {code}")
-
- # Get detailed 2FA info
- result = get_latest_2fa_code(minutes=10)
- if result:
- print(f"Code: {result['code']}")
- print(f"From: {result['sender']}")
- print(f"Message: {result['message']}")
+ python -m tools.sms_reader.cli 2fa
+ python -m tools.sms_reader.cli 2fa --minutes 10 --sender "+1555"
+ python -m tools.sms_reader.cli 2fa --detailed # full message info as JSON
# Recent messages
- messages = get_recent_messages(limit=10)
- for m in messages:
- print(f"{m['sender']}: {m['text']}")
-
- # Search
- results = search_messages("verification", limit=5)
- ```
-
- ## Functions
-
- | Function | Description |
- |----------|-------------|
- | `get_2fa(minutes=5)` | Returns just the code string, or None |
- | `get_latest_2fa_code(minutes=10)` | Returns dict with code, message, sender, date |
- | `get_recent_messages(limit=20, sender=None, since_minutes=None)` | List of message dicts |
- | `search_messages(query, limit=20)` | Search by content |
- | `list_senders(limit=50, since_days=30)` | List senders with message counts |
-
- ## Common Patterns
-
- ### Wait for 2FA code
- ```python
- from tools.sms_reader import get_2fa
- import time
-
- for _ in range(30): # 30 second timeout
- code = get_2fa(minutes=1)
- if code:
- print(f"Got code: {code}")
- break
- time.sleep(1)
- ```
+ python -m tools.sms_reader.cli recent
+ python -m tools.sms_reader.cli recent --limit 10 --sender "+1555" --since-minutes 30
- ### Get code from specific sender
- ```python
- from tools.sms_reader import get_latest_2fa_code
+ # Search messages by content
+ python -m tools.sms_reader.cli search "verification"
+ python -m tools.sms_reader.cli search "code" --limit 5
- # Partial match on sender
- result = get_latest_2fa_code(minutes=10, sender="+1555")
+ # List senders
+ python -m tools.sms_reader.cli senders
+ python -m tools.sms_reader.cli senders --limit 10 --since-days 7
```
## Requirements
- macOS with Messages app
- Full Disk Access for Python (System Settings > Privacy & Security > Full Disk Access)
- - Python.app added: `/Library/Frameworks/Python.framework/Versions/3.12/Resources/Python.app`
-
- ## Database Schema
-
- Key tables in `chat.db`:
- - `message` - text, date, is_from_me, handle_id
- - `handle` - phone numbers/emails
- - `chat` - conversation metadata
- - `chat_message_join` - links messages to chats
-
- Apple timestamps are nanoseconds since 2001-01-01 (add 978307200 seconds and divide by 1e9 for Unix time).