🇺🇸English
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:
- On iPhone: Settings → Messages → Text Message Forwarding
- 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)
Weekly Installs
96
Repository
letta-ai/skills
GitHub Stars
74
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubFailSocketPassSnykPass
Installed on
opencode84
gemini-cli83
codex82
cursor76
github-copilot75
cline69
