imsg

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

```bash
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:

```bash
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:

```bash
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:

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

Known DM thread:

```bash
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:

```bash
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:

```bash
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' --text "boom" --effect impact
imsg send-attachment --chat 'iMessage;-;+15551234567' \
  --reply-to <message-guid> --file /path/to/file.jpg
```

Formatting ranges are UTF-16 positions. Supported styles include `bold`, `italic`, `underline`, and `strikethrough`; use `--format-file` for generated JSON.

## Group Scenarios

From openclaw/openclaw, MIT.

More from openclaw/openclaw