Turn macOS Messages history into stable structured data.
MessageGlass is a read-only Apple Messages SDK for developers building local-first search, AI,
analytics, archival, and personal-data tools. It converts the undocumented macOS chat.db into a
normalized Rust and JSON model so your application does not have to own Apple-specific SQL, binary
decoders, or schema compatibility logic.
Apple Messages as data—not as an automation channel.
No sending. No server. No transport layer. Just a bounded, compatibility-aware interface over the Messages database.
Opening SQLite is easy. Reliably interpreting Messages is not:
message + chats + handles + attachments
+ attributedBody + reactions + replies + edits
+ Apple timestamps + schema variation
↓
MessageStore → Message
MessageGlass keeps those storage details behind an application-facing contract.
- Read-only by design — the core has no message-send capability and opens SQLite read-only and query-only.
- A normalized application model — consume messages, chats, senders, attachments, reactions, replies, rich text, and edit/unsend history without exposing table mechanics.
- Rich data without silent loss — preserve formatting, links, mentions, effects, body parts, inline-object positions, and attributes not yet understood.
- Explicit compatibility — inspect schema capabilities up front and receive structured errors instead of partially ingesting an unsupported database.
- Predictable resource use — bounded rows, retained memory, SQLite values, parser collections, and attachments fail safely rather than growing without limit.
- Incremental history processing — versioned opaque cursors let applications resume large newest-first scans without managing SQLite pagination state.
- Privacy-aware diagnostics —
msglass doctorreports database and schema metadata without reading chats or message rows.
MessageGlass requires macOS and Full Disk Access when reading the live Messages database.
cargo install --git https://github.com/tamesystems/messageglass
msglass doctor
msglass messages --limit 25
msglass page --limit 100Output is JSON Lines by default, with JSON and text formats also available. A copied compatible
chat.db can be selected with --db.
msglass --db /path/to/chat.db messages --format jsonuse messageglass::db::MessageStore;
use std::path::Path;
let store = MessageStore::open(Path::new("/path/to/copied/chat.db"))?;
let page = store.message_page(100, None, None)?;
for message in page.messages {
println!("{}", message.guid);
}
# Ok::<(), messageglass::db::StoreError>(())Message.text is the convenient plain-text view. Message.rich_body retains attributed ranges and
ordered inline components, while Message.edits exposes edit and unsend history.
- local-first search and personal knowledge tools;
- AI/RAG or MCP adapters that need Messages as a data source;
- Rust desktop, CLI, and native-service applications;
- analytics, archival, and personal-data pipelines;
- teams replacing hand-written Messages SQL and decoders.
MessageGlass is intentionally not a sending bot, realtime Messages bridge, PDF/HTML exporter, iOS-backup reader, or forensic/e-discovery product. That narrower boundary is the product.
MessageGlass performs no network operations and does not mutate Messages. Reading the live database still requires Full Disk Access, which is a powerful macOS permission. Downstream applications can transmit any data they read, so audit the complete application—not only this library.
- Getting started and CLI usage
- Library architecture, data model, and security boundaries
- Schema compatibility and resource limits
- Development, fixtures, fuzzing, and release checks
- Contributing
- Security policy and private reporting
- Changelog
Apple does not publish chat.db as a supported application API. MessageGlass therefore promises a
controlled application-facing boundary and explicit compatibility failures—not permanent support
for every past or future Messages schema.