imsg

iMessage

Read and send iMessages and SMS from the terminal via the imsg CLI.

Setup (Panda)

• Messages.app signed in as: the agent Apple ID (see USER.md)
• Joel's iMessage address: see USER.md → imessage
• Full Disk Access must be granted to the terminal for read operations (chats, history, watch)
• Automation permission for Messages.app required for send
• imsg send returns "sent" optimistically — this means AppleScript fired, not delivery confirmed

Commands

List chats

imsg chats --limit 10 --json

Read history

imsg history --chat-id <id> --limit 20 --attachments --json

Watch for new messages

imsg watch --chat-id <id> --attachments

Send

# By email (iMessage)
imsg send --to "[email protected]" --text "hello"

# By phone number (iMessage or SMS)
imsg send --to "+18005551234" --text "hello"

# With file attachment
imsg send --to "[email protected]" --text "see attached" --file /​path/​to/​file.jpg

Delivery Notes

• "sent" from CLI = AppleScript successfully handed off to Messages.app
• "Not delivered" in Messages.app = actual delivery failure (auth issue, recipient offline, etc.)
• Full Disk Access missing = read commands fail with permissionDenied; send still works via AppleScript
• Messages appear as coming from the agent Apple ID, not from Joel

Sending to Joel

Joel's iMessage address is in USER.md (imessage field). Use it to notify him directly:

imsg send --to "<joel-imessage>" --text "your message"

Safety

• Read-only by default — use chats and history before sending
• Always confirm recipient and message text before imsg send
• --json flag preferred for all read operations (deterministic parsing)

Install

brew install steipete/​tap/​imsg

Credit

CLI by steipete. Adopted per ADR-0067.