Skip to main content
Agent skill

Imsg

Use the imsg CLI from OpenClaw agents for iMessage/SMS DMs, groups, replies, reactions, polls, watching, and private-API actions.

Get started

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?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/imsg
# Save SKILL.md to ~/.claude/skills/imsg/SKILL.md
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.