Skip to main content
SimpleClaw integrates with iMessage on macOS, providing native Apple Messages support for direct messages and group chats.

​
Features

  • Direct messages and group chats
  • Media support (images, videos, documents)
  • Native macOS integration
  • SMS/MMS support (if iPhone connected)
  • Reply threading
  • Works with existing Messages.app conversations

​
Requirements

  • macOS 10.14 (Mojave) or later
  • Messages.app configured with iMessage account
  • Full Disk Access permission for SimpleClaw
  • imsg CLI tool (bundled with SimpleClaw)

​
Setup

1

Grant Full Disk Access

SimpleClaw needs access to Messages database:
  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Click the lock and authenticate
  3. Click ”+” and add Terminal (or your terminal app)
  4. If using SimpleClaw macOS app, add it to the list
Full Disk Access is required to read the Messages database at ~/Library/Messages/chat.db
2

Enable iMessage Channel

simpleclaw config set channels.imessage.enabled true
3

Verify Configuration

simpleclaw channels status imessage
You should see iMessage as enabled and configured.
4

Test Sending

Send a test message:
simpleclaw message send imessage [email protected] "Test message"
Or to a phone number:
simpleclaw message send imessage +1234567890 "Test SMS"

​
Configuration

​
Basic Configuration

channels:
  imessage:
    enabled: true

​
Custom Paths

channels:
  imessage:
    enabled: true
    cliPath: "/usr/local/bin/imsg"  # Custom imsg path
    dbPath: "~/Library/Messages/chat.db"  # Custom Messages database path

​
Service Selection

channels:
  imessage:
    enabled: true
    service: "iMessage"  # Options: iMessage, SMS

​
Multi-Account Setup

channels:
  imessage:
    enabled: true
    accounts:
      personal:
        enabled: true
        name: "Personal"
        service: "iMessage"
      sms:
        enabled: true
        name: "SMS"
        service: "SMS"

​
Security

​
DM Policy

channels:
  imessage:
    dmPolicy: pairing  # Options: open, pairing, allowlist, off
    allowFrom:
      - "[email protected]"  # Email or phone number
      - "+1234567890"

​
Group Policy

channels:
  imessage:
    groupPolicy: allowlist  # Options: allowlist, open, off
    groupAllowFrom:
      - "[email protected]"  # Who can trigger in groups

​
Pairing Workflow

With dmPolicy: pairing:
  1. User sends first message
  2. Approve: simpleclaw pairing approve imessage [email protected]
  3. User receives approval notification

​
Message Features

​
Sending Messages

# Send to iMessage user (email)
simpleclaw message send imessage [email protected] "Hello!"

# Send to phone number (SMS if not iMessage)
simpleclaw message send imessage +1234567890 "Hello!"

# Send with media
simpleclaw message send imessage [email protected] "Photo" --media-url "/path/to/image.jpg"

# Reply to message
simpleclaw message send imessage [email protected] "Reply" --reply-to message-guid

# Send to group (use chat ID)
simpleclaw message send imessage "chat_id:123" "Group message"

​
Target Formats

  • Email: [email protected]
  • Phone: +1234567890 (E.164 format recommended)
  • Chat ID: chat_id:123 (for groups)

​
Media Support

channels:
  imessage:
    mediaMaxMb: 100  # Maximum media file size
Supported media types:
  • Images: JPEG, PNG, GIF, HEIC
  • Videos: MOV, MP4, M4V
  • Documents: PDF and others

​
Reply Threading

iMessage supports replying to specific messages: 
simpleclaw message send imessage [email protected] "Reply" --reply-to "message-guid"

​
Group Chats

​
Finding Group Chat IDs

Group chats use internal chat IDs from Messages database. You can:
  1. Check SimpleClaw logs for incoming group messages
  2. Query Messages database (advanced): 
    SELECT ROWID, chat_identifier, display_name FROM chat WHERE chat_identifier LIKE '%chat%';

​
Group Configuration

iMessage groups use account-level policies: 
channels:
  imessage:
    groupPolicy: allowlist
    groupAllowFrom:
      - "[email protected]"  # Who can trigger

​
Advanced Configuration

​
Region Settings

For region-specific phone number handling: 
channels:
  imessage:
    region: "US"  # ISO 3166-1 alpha-2 country code

​
Custom CLI Path

If imsg is installed in a non-standard location: 
channels:
  imessage:
    cliPath: "/custom/path/to/imsg"

​
Custom Database Path

channels:
  imessage:
    dbPath: "/custom/path/to/chat.db"

​
Default Recipient

channels:
  imessage:
    defaultTo: "[email protected]"

​
Troubleshooting

Ensure Full Disk Access is granted:
  1. System Settings → Privacy & Security → Full Disk Access
  2. Add Terminal or SimpleClaw app
  3. Restart terminal/app after granting access
Test database access:
sqlite3 ~/Library/Messages/chat.db "SELECT COUNT(*) FROM chat;"
Verify imsg is installed:
which imsg
imsg --version
If not found, it should be bundled with SimpleClaw. Check installation.
Verify Messages.app is working:
  1. Open Messages.app
  2. Send a test message manually
  3. Check iMessage is signed in (Settings → iMessage)
Check SimpleClaw status:
simpleclaw channels status imessage --probe
SMS requires iPhone connected via Text Message Forwarding:
  1. On iPhone: Settings → Messages → Text Message Forwarding
  2. Enable forwarding to your Mac
  3. Verify on Mac in Messages preferences
Check database access and ensure the group exists in Messages.app.Group messages may require specific chat IDs from the database.

​
CLI Commands

# Enable channel
simpleclaw config set channels.imessage.enabled true

# Status
simpleclaw channels status imessage
simpleclaw channels status imessage --probe

# Send message
simpleclaw message send imessage <handle> <message>

# Pairing
simpleclaw pairing approve imessage [email protected]
simpleclaw pairing list imessage

​
Limitations

  • macOS only (no Windows/Linux support)
  • Requires Full Disk Access permission
  • Depends on Messages.app and iMessage service
  • SMS requires iPhone with Text Message Forwarding
  • Group chat IDs can be difficult to determine
  • No native poll or advanced reaction support

​
API Reference

iMessage channel implementation: extensions/imessage/src/channel.ts

​
Channel ID

imessage (alias: imsg)

​
Target ID Format

​
Capabilities

  • Chat types: direct, group
  • Features: media
  • Delivery mode: direct
  • Text chunk limit: 4000 characters

​
Configuration Schema

See IMessageConfigSchema in source for full schema.

​
Best Practices

Grant Full Disk Access

Required for Messages database access

Use E.164 for Phone Numbers

International format ensures proper routing:
+1234567890

Enable Pairing

Control who can message:
dmPolicy: pairing

Limit Media Size

Prevent large files:
mediaMaxMb: 50

​
Next Steps

Security Configuration

Configure DM policies and allowlists

Multi-Channel Setup

Connect additional platforms

Build docs developers (and LLMs) love

Get started for freeTalk to us