imessage

majiayu000's avatarfrom majiayu000

Interact with Messages app - read conversations, send messages, and check for new messages using AppleScript and SQLite database access

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Communication Tools]

When & Why to Use This Skill

This Claude skill enables seamless integration with the macOS Messages app, allowing agents to read, send, and monitor iMessages and SMS directly. By leveraging AppleScript and SQLite database access, it empowers users to automate text-based communication, manage contact outreach, and streamline messaging workflows within the Apple ecosystem. It is an essential tool for developers and power users looking to bridge the gap between AI agents and personal or professional mobile messaging.

Use Cases

  • Automated Appointment Scheduling: Use the agent to coordinate with clients and send booking confirmations or reminders via iMessage/SMS.
  • Proactive Customer Outreach: Automate follow-up messages to leads or existing customers to maintain engagement and improve conversion rates.
  • Real-time Message Monitoring and Alerts: Configure the agent to watch for specific incoming texts and trigger automated workflows or instant notifications.
  • Seamless Document Sharing: Send files, images, and technical attachments to contacts directly through the Messages interface as part of an automated business pipeline.
  • Personal Assistant Workflows: Delegate tasks like checking unread messages or drafting natural-sounding replies to the AI agent while maintaining a human touch.
nameimessage
descriptionSend and read iMessages/SMS from macOS. Use for texting contacts, scheduling services, or automating message-based workflows. Triggers on queries about texting, messaging, SMS, iMessage, or contacting someone via text.

iMessage Integration

Send and read iMessages/SMS using the imsg CLI tool on macOS.

Setup

1. Build the imsg CLI

Clone and build the tool:

git clone https://github.com/letta-ai/imsg.git ~/repos/imsg
cd ~/repos/imsg
swift build -c release

The binary will be at ~/repos/imsg/.build/release/imsg (or use the pre-built binary if available at ~/repos/imsg/bin/imsg).

2. Grant Permissions

Required macOS permissions (System Settings → Privacy & Security):

Permission Location Required For
Full Disk Access Privacy & Security → Full Disk Access Reading message history
Automation Privacy & Security → Automation Sending messages via Messages.app

3. Enable SMS Relay (Optional)

To send SMS (green bubbles) to non-iMessage users:

  1. On iPhone: Settings → Messages → Text Message Forwarding
  2. Enable forwarding to your Mac

Commands

List Recent Chats

imsg chats --limit 10
imsg chats --limit 10 --json

Output format: [chat_id] (identifier) last=timestamp

View Chat History

# View last 20 messages in a chat
imsg history --chat-id <id> --limit 20

# With attachments metadata
imsg history --chat-id <id> --limit 20 --attachments

# Filter by date
imsg history --chat-id <id> --start 2026-01-01T00:00:00Z --json

Send a Message

# Send to phone number
imsg send --to "+15555555555" --text "Hello!"

# Send with attachment
imsg send --to "+15555555555" --text "Here's the file" --file /path/to/file.jpg

# Force iMessage or SMS
imsg send --to "+15555555555" --text "Hi" --service imessage
imsg send --to "+15555555555" --text "Hi" --service sms

# Send to existing chat by ID
imsg send --chat-id 86 --text "Hello!"

Watch for New Messages

imsg watch --chat-id <id> --debounce 250ms

Best Practices

Phone Number Format

  • Use E.164 format: +1XXXXXXXXXX for US numbers
  • Include country code for international

SMS vs iMessage

  • iMessage (blue bubble): Default for Apple device users, free
  • SMS (green bubble): Requires iPhone relay, may have carrier charges
  • Use --service sms when recipient doesn't have iMessage

Message Etiquette for Agents

  • Be concise - Keep messages short and clear
  • Be human - Write naturally, not robotically
  • Identify context - If following up, reference previous conversation
  • Respect timing - Avoid early morning/late night messages

Common Use Cases

Scheduling Services

imsg send --to "+14155551234" --text "Hi! Do you have availability this Saturday for a cleaning?"

Following Up

imsg send --to "+14155551234" --text "Just wanted to follow up on my earlier message. Let me know when you have a chance!"

Confirming Appointments

imsg send --to "+14155551234" --text "Confirming our appointment for Saturday at 10am. See you then!"

Troubleshooting

Issue Solution
"not authorized" error Grant Automation permission to terminal
Can't read messages Grant Full Disk Access to terminal
SMS not sending Enable Text Message Forwarding on iPhone
Message stuck sending Check Messages.app is signed in and working

Technical Notes

  • Uses AppleScript for sending (no private APIs)
  • Read operations are read-only on the Messages SQLite database
  • Requires macOS 14+ with Messages.app configured
  • Binary location: ~/repos/imsg/bin/imsg (adjust path as needed)