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 ```bash imsg chats --limit 10 --json ``` ### Read history ```bash imsg history --chat-id <id> --limit 20 --attachments --json ``` ### Watch for new messages ```bash imsg watch --chat-id <id> --attachments ``` ### Send ```bash # 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: ```bash 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 ```bash brew install steipete/tap/imsg ``` ## Credit CLI by [steipete](https://github.com/steipete/imsg). 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`.