TL;DR
iMessage-kit is a type-safe SDK for macOS that provides methods to read, send and automate iMessage conversations. It supports real-time watching, scheduling, attachments, plugins and works with Bun or Node.js (requires better-sqlite3 for Node).
What happened
Photon’s imessage-kit is an SDK aimed at developers building automation, AI agents and chat-first apps that interact with Apple’s Messages on macOS. The toolkit exposes methods to send text, images and files, query and list chats, watch messages in real time, and create automated replies or batch sends. It also includes a scheduling layer (MessageScheduler) and a human-friendly Reminders wrapper for natural-language scheduling. Attachments helpers let code check, download and classify files; a plugin system enables hooks before and after sends; and error classes cover send, database and platform failures. The package supports Bun with no dependencies and Node.js with a better-sqlite3 requirement. Using imessage-kit requires granting Full Disk Access on macOS so the SDK can read chat history and perform automation tasks.
Why it matters
- Provides programmatic access to iMessage on macOS for automation, bots and integrations.
- Built-in scheduling and reminders simplify timed or recurring messaging workflows.
- Real-time watching and message-chain APIs enable responsive automation and auto-replies.
- Plugin and webhook support allow integration with external systems and custom logging or transformations.
Key facts
- Core capabilities include send(), sendFile(), getMessages(), listChats(), startWatching(), and stopWatching().
- Supports sending text, local and network images, and a wide range of file types (PDF, DOCX, CSV, MP4, MP3, etc.).
- Scheduling provided via MessageScheduler; Reminders offers natural-language scheduling helpers (in, at, exact, recurring).
- Real-time callbacks available for all messages, direct messages, and group messages; can be used for auto-replies.
- Includes attachment helper utilities such as attachmentExists(), downloadAttachment(), and getters for size/type checks.
- Plugin system lets developers register hooks (onInit, onBeforeSend, onAfterSend, onDestroy) and use built-in loggerPlugin.
- Error classes mentioned include SendError, DatabaseError and PlatformError for structured handling.
- Installation: bun add @photon-ai/imessage-kit for Bun; npm install @photon-ai/imessage-kit better-sqlite3 for Node.js.
- Requires granting Full Disk Access in macOS Privacy & Security settings to read Messages database and run automations.
- Examples and recipes are provided (send text/image/file, list chats, watch messages, auto-reply, scheduling, plugins).
What to watch next
- Advanced features such as threaded replies, tapbacks, message editing, unsending and live typing indicators are called out as part of an 'Advanced iMessage Kit' — contact daniel@photon.codes for details.
- The SDK requires Full Disk Access on macOS; users and administrators should verify permissions before deploying automation.
- not confirmed in the source
Quick glossary
- SDK: A software development kit: a collection of tools, libraries and documentation that helps developers build applications for a specific platform or service.
- Full Disk Access: A macOS privacy permission that allows an app or process to read data across the file system, including user data and system files.
- Webhook: A user-provided HTTP callback that an application can call to notify external services about events or deliver data.
- Plugin: A modular piece of code that extends an application's behavior by running custom logic at defined lifecycle points (init, before/after send, destroy).
- Attachment helper: Utility functions that check for, identify, measure and download message attachments such as images, videos or documents.
Reader FAQ
Which platforms does imessage-kit support?
The source states the SDK is for macOS.
How do I install imessage-kit?
For Bun: bun add @photon-ai/imessage-kit. For Node.js: npm install @photon-ai/imessage-kit better-sqlite3.
Does the SDK require special permissions?
Yes. It requires Full Disk Access on macOS to read chat history and run automation tasks.
Does imessage-kit include threaded replies, message editing or live typing indicators?
The source points users to an 'Advanced iMessage Kit' for those features and provides contact info; availability in the base SDK is not confirmed in the source.
Is imessage-kit open source or free to use?
not confirmed in the source
@photon-ai/imessage-kit A type-safe, elegant iMessage SDK for macOS with cross-runtime support A full-featured iMessage SDK for reading, sending, and automating iMessage conversations on macOS. Perfect for building AI agents, automation…
Sources
- iMessage-kit is an iMessage SDK for macOS
- A developer-first way to work with iMessage.
- Deep Dive into iMessage – Behind the Making of an Agent
- photon-ai/advanced-imessage-kit
Related posts
- I’d tell a UDP joke, but you might not receive it — CodePuns dev humor
- Chronon (chr2): Rust consensus + durable outbox for exactly-once side effects
- Using FUSE to Give Agents Broad, Sandboxable Access via Filesystems