mcpField
I
imsg

imsg

github.com/joelhooksProductivity6541 installsUpdated 2d ago
Repository

About imsg

imsg is a skill for reading and sending iMessage and SMS from a terminal using the imsg CLI. It supports workflows involving Messages.app, with commands for chat lists, history, message watching, and attachments, plus guidance on permissions and send confirmation.

Key features

  1. 01List chats and read message history
  2. 02Watch for new messages and attachments
  3. 03Send to email addresses or phone numbers
  4. 04Send file attachments
  5. 05Document permissions and sending safeguards

Use cases

  1. 01Read chat history in JSON format
  2. 02Watch a chat for new messages
  3. 03Send a message or file attachment

MCP support

The README also describes using an iMessage MCP service through Executor on Flagg for status, chats, history, and sending. The send tool requires explicit approval of the recipient and text.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/joelhooks/joelclaw --skill imsg

After installing, type/imsgin Claude Code to confirm it loaded.

Bundled filesagents/openai.yaml

Details

From the project README

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.

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.

Comments

Markdown supported