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.