/imsg

name: imsg
description: "Use the imsg CLI from OpenClaw agents for iMessage/SMS DMs, groups, replies, reactions, polls, watching, and private-API actions."
homepage: https://imsg.to
metadata:
  {
    "openclaw":
      {
        "emoji": "📨",
        "os": ["darwin"],
        "requires": { "bins": ["imsg"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "steipete/tap/imsg",
              "bins": ["imsg"],
              "label": "Install imsg (brew)",
            },
          ],
      },
  }

imsg

Use the generic `message` tool first for actions that its current iMessage schema exposes. Use `imsg` when the task needs local Messages.app history, target discovery, watching, or an administrative/private-API capability that is not exposed by `message`.

Do not use this skill for Telegram, Signal, WhatsApp, Discord, Slack, or for replying inside the current OpenClaw conversation when the configured channel already routes the reply.

Agent Flow

1. Resolve the conversation first. 2. Choose DM, existing group, or new group. 3. Prefer an available `message` action; otherwise pick the lowest-capability `imsg` command that preserves the requested semantics. 4. Confirm any send or visible state change unless the user already gave exact recipient, content, and action. 5. Execute with stable identifiers: prefer `--chat-id` for normal sends/watch/history and `--chat` chat GUID for bridge actions.

Never infer a recipient from a casual name alone when several chats or handles could match. Show the matched display name, handle(s), group participants, and message text/action before sending.

Host Requirements

• macOS 14+ with Messages.app signed in for send/react/bridge actions.
• Private API mode is strongly encouraged for OpenClaw iMessage. It unlocks replies, precise tapbacks, effects, polls, attachment replies, read/typing actions, and group management. Basic mode is a fallback for reads plus plain text/file send.
• Full Disk Access for the process context that runs `imsg` or OpenClaw; reads fail without Messages DB access.
• Automation permission for Messages.app when using public `send`.
• Accessibility permission for the process context that runs public `imsg react`; it uses System Events UI automation. Bridge `tapback` uses private API instead.
• Optional Contacts permission for contact-name resolution.
• SMS sends require Text Message Forwarding from the user's iPhone to this Mac.
• Linux reads a copied `chat.db` only; it cannot send, react, launch Messages.app, mark read, or type.

Resolve Targets

Use `--json` reads. Output is newline-delimited JSON; use `jq -s` when `jq` is available, or consume one object per line directly.

imsg chats --limit 25 --json | jq -s
imsg search --query "dinner" --match contains --json | jq -s
imsg history --chat-id 42 --limit 20 --attachments --json | jq -s
imsg group --chat-id 42 --json

Target rules:

• DM to a phone/email: use `imsg send --to` when the user gave an exact handle, or after a single unambiguous chat match.
• Existing DM thread: `imsg send --chat-id <id>` is safer than re-resolving a name.
• Existing group: inspect with `imsg group --chat-id <id> --json`; send with `--chat-id`, bridge with the chat GUID from `group`.
• New group: use `chat-create` only when the user explicitly asked to create a group or no existing group matches.
• Ambiguous group names: confirm participants, not just display name.
• SMS: use `--service sms` only when requested or when iMessage fallback is not desired. SMS relay requires Text Message Forwarding.

Do not make `jq` a hard prerequisite for the skill; it is only a convenient formatter for examples.

Capability Choice

Use `imsg` standard commands when the current `message` schema does not cover the operation or when local history is needed:

• Read/list/search/watch: `chats`, `group`, `history`, `search`, `watch`
• Basic text/file send: `send`
• Standard tapback to most recent incoming message in a chat: `react`

Use the private API bridge for the native iMessage actions OpenClaw users normally expect:

• Rich replies, text formatting, effects, subjects, multipart sends
• Native Apple Messages polls and poll votes
• Tapback by message GUID or tapback removal
• Edit, unsend, delete, notify anyways
• Read receipts, typing indicators, bridge event watch
• Group create/name/photo/member/leave/delete/mark actions
• Account, whois, nickname checks

For OpenClaw channel setup, check bridge availability early:

imsg status --json

If the host supports bridge actions but Messages is not injected yet, ask before running `imsg launch`. It kills and relaunches Messages.app to inject the bridge, so treat it as a visible state change:

imsg launch
imsg status --json

If SIP, library validation, private entitlement checks, or missing selectors still block the capability, explain that the requested private-API action is unavailable on this host and offer the closest non-bridge action, if one exists. Do not silently downgrade a threaded reply, effect, subject, poll, or GUID-targeted tapback into a plain send/react.

DM Scenarios

Exact handle, basic send:

imsg send --to "+14155551212" --text "On my way" --service auto

Known DM thread:

imsg send --chat-id 42 --text "On my way"
imsg send --chat-id 42 --file /path/to/photo.jpg

Force channel only when the user asks:

imsg send --to "+14155551212" --text "green bubble" --service sms
imsg send --to "+14155551212" --text "iMessage only" --service imessage --no-sms-fallback

Threaded reply, formatting, effects, or attachment reply:

imsg send-rich --chat 'iMessage;-;+15551234567' \
  --reply-to <message-guid> --text "reply text"
imsg send-rich --chat 'iMessage;-;+15551234567' --text 'hello world' \
  --format '[{"start":0,"length":5,"styles":["bold"]}]'
imsg send-rich --chat 'iMessage;-;+15551234567' --