SoleOS iMessage Agent

Connects your Mac's iMessage to SoleOS. Runs locally on your Mac, reads incoming messages from the macOS Messages database, and sends outbound messages via AppleScript.

Quick Start

npx soleos-imessage --key YOUR_API_KEY

Setup

1. Generate an API key in SoleOS Settings (Settings > API Keys > Generate iMessage Key).

2. Grant Full Disk Access to your terminal app:

   • Open System Settings > Privacy & Security > Full Disk Access
   • Add Terminal (or iTerm, Warp, etc.)
   • This is required to read the iMessage database (~/Library/Messages/chat.db)

3. Run the agent:

   npx soleos-imessage --key sk_live_abc123

4. Keep it running in the background. The agent polls for new messages and outbound sends on a regular interval.

Options

| Flag | Description | Default | |------|-------------|---------| | --key <key> | SoleOS API key (required) | — | | --url <url> | SoleOS server URL | https://soleos.vercel.app | | --interval <seconds> | Polling interval | 30 |

How It Works

• Incoming messages: The agent reads new iMessages from ~/Library/Messages/chat.db using SQLite and forwards them to SoleOS via the inbound API.
• Outgoing messages: The agent polls SoleOS for pending outbound messages and sends them via AppleScript through the Messages app.
• Heartbeat: A heartbeat is sent every 60 seconds so SoleOS knows the agent is online.
• Cursor tracking: The last-read message position is stored in ~/.soleos-imessage-cursor so no messages are missed across restarts.

Requirements

• macOS with iMessage configured and signed in
• Node.js 18+
• Full Disk Access granted to your terminal
• A SoleOS account with an API key

Troubleshooting

"Cannot open chat.db" Grant Full Disk Access to your terminal app in System Settings > Privacy & Security.

"Registration failed" Check that your API key is valid and the SoleOS server is reachable.

Messages not sending Ensure the Messages app is open and signed in to iMessage. The recipient must be reachable via iMessage.