| name | osascript-data |
| description | Read macOS app SQLite databases directly. Use when reading iMessage chat history, Chrome browsing history, Safari history, or any local app SQLite DB. Always copy the DB before querying — most apps lock the file while running. |
osascript-data
Direct SQLite access to macOS app databases. No API, no auth — plain file reads.
All scripts are pure Python using stdlib only (sqlite3, shutil).
The Universal Rule
Always copy before querying. Most apps (Chrome, Messages) lock their DB while running.
shutil.copy2(db_path, "/tmp/copy.db")
conn = sqlite3.connect("/tmp/copy.db")
Key Databases
| App | Path | Permission needed |
|---|
| iMessage + SMS | ~/Library/Messages/chat.db | Full Disk Access |
| Chrome History | ~/Library/Application Support/Google/Chrome/Default/History | Full Disk Access |
| Safari History | ~/Library/Safari/History.db | Full Disk Access |
| TCC permissions | ~/Library/Application Support/com.apple.TCC/TCC.db | Full Disk Access |
Scripts
Run a raw SQL query against any DB (copy-first):
uv run scripts/sqlite-query.py ~/Library/Messages/chat.db "SELECT * FROM message LIMIT 10"
Read recent iMessages with sender, timestamp, and direction:
uv run scripts/imessage-read.py
uv run scripts/imessage-read.py 50
uv run scripts/imessage-read.py 20 "John"
Read Chrome browsing history (Windows epoch → UTC):
uv run scripts/chrome-history.py
uv run scripts/chrome-history.py 50 github
Read Safari browsing history (CoreData epoch → UTC):
uv run scripts/safari-history.py
uv run scripts/safari-history.py 50 github
Audit TCC.db — see all app privacy permission grants:
uv run scripts/permissions-audit.py
uv run scripts/permissions-audit.py --service kTCCServiceCamera
uv run scripts/permissions-audit.py --allowed
Reference
iMessage Agent Loop Pattern
chat.db (SQLite) → read new message → Python/Claude reasons → osascript → Messages app → sends reply
See reference/06-sqlite.md for the full pattern with WatchPaths trigger.