Imsg
Use the imsg CLI from OpenClaw agents for iMessage/SMS DMs, groups, replies, reactions, polls, watching, and private-API actions.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Imsg when an AI agent needs a reusable SKILL.md workflow for this job: Use the imsg CLI from OpenClaw agents for iMessage/SMS DMs, groups, replies, reactions, polls, watching, and private-API actions.
When not to use it
Skip Imsg when the task is outside the productivity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/imsg # Save SKILL.md to ~/.claude/skills/imsg/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/imsg/SKILL.md. For a shared project, commit the folder at .claude/skills/imsg/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Imsg skill for this task: Use Imsg when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 73/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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
Inspect before acting:
```bash imsg group --chat-id 42 --json imsg history --chat-id 42 --limit 20 --json | jq -s ```
Send to an existing group:
```bash imsg send --chat-id 42 --text "Works for me" ```
Bridge reply or poll in an existing group:
```bash imsg send-rich --chat 'iMessage;+;chat0000' \ --reply-to <message-guid> --text "replying in thread" imsg poll send --chat 'iMessage;+;chat0000' \ --question "Dinner?" --option "Pizza" --option "Sushi" ```
Create or mutate groups only on explicit request:
```bash imsg chat-create --addresses '+15551111111,+15552222222' --name 'Crew' --text 'gm' imsg chat-name --chat 'iMessage;+;chat0000' --name 'Renamed' imsg chat-photo --chat 'iMessage;+;chat0000' --file /path/to/group.jpg imsg chat-add-member --chat 'iMessage;+;chat0000' --address +15553333333 imsg chat-remove-member --chat 'iMessage;+;chat0000' --address +15553333333 imsg chat-leave --chat 'iMessage;+;chat0000' imsg chat-delete --chat 'iMessage;+;chat0000' imsg chat-mark --chat 'iMessage;+;chat0000' --read ```
Group mutations are highly visible. Confirm the exact group and participant list before changing membership, name, photo, read state, leaving, or deleting.
## Reactions and Replies
Public `react` is limited: it reacts to the most recent incoming message in the chat.
```bash imsg react --chat-id 42 --reaction like imsg react --chat-id 42 --reaction love imsg react --chat-id 42 --reaction dislike imsg react --chat-id 42 --reaction laugh imsg react --chat-id 42 --reaction emphasis imsg react --chat-id 42 --reaction question ```
For a specific message GUID or removal, use bridge `tapback`:
```bash imsg tapback --chat 'iMessage;-;+15551234567' --message <message-guid> --kind love imsg tapback --chat 'iMessage;-;+15551234567' --message <message-guid> --kind love --remove ```
Use `send-rich --reply-to <message-guid>` for threaded replies. Confirm the referenced message if the user says "that" or "the previous one".
## Polls
Native Apple Messages polls require the bridge. Creation needs at least two `--option` values. Voting requires one of `--option-id`, `--option-index`, or `--option`.
Messages renders only the options on a poll balloon, so current `imsg poll send` echoes `--question` as a best-effort plain caption after the poll. Use `--comment` to override that caption. Do not retry automatically when only the caption fails: the poll may already be delivered.
```bash imsg poll send --chat 'iMessage;-;+15551234567' \ --question "Dinner?" --option "Pizza" --option "Sushi" --comment "Vote by 5pm" imsg poll send --chat 'iMessage;+;chat0000' --reply-to <message-guid> \ --question "Approve?" --option "Yes" --option "No" imsg poll vote --chat 'iMessage;+;chat0000' \ --poll <poll-message-guid> --option-id <option-id> ```
Find poll IDs and options with:
```bash imsg history --chat-id 42 --limit 20 --json | jq -s '.[] | select(.poll != null) | {guid, poll}' ```
`history` and `watch` backfill a title-less inbound native poll's `poll.question` from its clean caption row. Poll vote rows are `poll` events, not tapbacks; `watch --reactions` is not required to see them.
## Watch and Long-Running Agents
For a short one-off wait, use `watch`:
```bash imsg watch --chat-id 42 --since-rowid 9000 --json imsg watch --chat-id 42 --attachments --convert-attachments --json imsg watch --chat-id 42 --reactions --json imsg watch --chat-id 42 --bb-events --json ```
`--since-rowid` is exclusive. Without it, `watch` starts at the newest row. `watch` uses filesystem events plus a low-frequency polling fallback, so it can catch up after missed SQLite sidecar events. Poll objects appear without `--reactions`.
For a daemon or multi-chat integration, use `imsg rpc`. It speaks JSON-RPC 2.0 over stdin/stdout. Inspect `imsg status --json` for `rpc_methods` before using newer bridge or poll methods.
## Safety Rules
- Confirm recipient, chat, and content before every send unless the user's request already contains exact values. - Confirm visible state changes: read receipts, typing indicators, edits, unsends, deletes, poll votes, tapbacks, group membership, group name/photo, leaving/deleting chats. - Never send to unknown numbers or ambiguous contact-name matches without approval. - Confirm attachments exist and are the intended files. - Prefer E.164 phone numbers; use `--region US` or another region only when needed for local formats. - Use bridge actions for bridge-only semantics, but confirm visible state changes and destructive actions first.
Intended uses
- Use Imsg when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.