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 "user@example.com" --text "hello"

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

# With file attachment
imsg send --to "user@example.com" --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.

Flagg: imsg via Executor

On Flagg, do not call imsg from a terminal for reads. Use Executor's saved connection, which runs a signed service that holds the Full Disk Access grant.

• Address: tools.imsg.org.flaggImsg.<tool>. Discover with tools.search({ namespace: "imsg", query: "" }).
• Tools: imsg_status, imsg_chats, imsg_group, imsg_history, imsg_send. Call imsg_status first.
• Service: LaunchAgent com.joel.imsg-mcp on 127.0.0.1:4793, code in packages/imsg-mcp, bundle /Applications/imsg-mcp.app.
• imsg_send needs Joel's explicit approval for recipient and text. An org require_approval policy on it is expected in Executor; check the Tools tab. Attachments only from ~/.joelclaw/imsg-outbox or /tmp. A killed send returns "outcome unknown", so check Messages.app before retrying.
• Health: curl -s http://127.0.0.1:4793/healthz and launchctl print gui/501/com.joel.imsg-mcp. Restart with launchctl kickstart -k gui/501/com.joel.imsg-mcp.
• Bearer: imsg_mcp_bearer_token in agent-secrets. Never print it.
• Joel-only grants: Full Disk Access for /Applications/imsg-mcp.app (re-toggle after any re-sign) and the Automation prompt for Messages.app on first send.

Full receipts: ~/Code/joelhooks/dark-wizard/.brain/projects/imsg-mcp-executor-2026-09.svx.