Redirected from /steipete/imsg
imsg

https://github.com/openclaw/imsg
Admin
imsg is a macOS command-line tool for reading and streaming messages from Messages.app, sending...
Tokens:80,521
Snippets:527
Trust Score:8.8
License:MIT
Update:5 hours ago
Show doc for...
Tokens:
Raw
### Fish completions installation

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

Generates a fish completion script and redirects it to the fish completions directory. Fish picks up new completions on next launch; no extra setup required.

```bash
imsg completions fish > ~/.config/fish/completions/imsg.fish
```

--------------------------------

### Build the helper dylib for source installs

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Source installs must run `make build-dylib` before launching. It produces `.build/release/imsg-bridge-helper.dylib` (arm64e).

```bash
make build-dylib   # produces .build/release/imsg-bridge-helper.dylib (arm64e)
```

--------------------------------

### Install imsg via Homebrew

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

Recommended installation method. Downloads the universal binary for your architecture, installs it onto your PATH, and tracks updates with brew upgrade.

```bash
brew install steipete/tap/imsg
```

--------------------------------

### Install, configure, and uninstall the imsg LaunchAgent

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Use these commands to install a per-user LaunchAgent that restores the bridge at login and checks it periodically. The interval defaults to 300 seconds and must be an integer of at least 60 seconds; reinstall to change it. --agent-interval requires --install-agent, and both agent flags are mutually exclusive with --kill-only and --force. Installation requires SIP disabled and a discoverable helper dylib, and refuses to install if either check fails.

```bash
imsg launch --install-agent
```

```bash
imsg launch --install-agent --agent-interval 600  # check every ten minutes
```

```bash
imsg launch --uninstall-agent
```

--------------------------------

### Launch Messages with custom dylib and kill-only

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Use `imsg launch` to start Messages with a custom dylib, quit without relaunching, or get machine-readable output. The `--dylib` path is authoritative; if missing, launch reports and stops. `--kill-only` tears down Messages without relaunching.

```bash
imsg launch --dylib /path/to/custom.dylib
imsg launch --kill-only           # quit Messages without launching
imsg launch --json                # machine-readable launch result
```

--------------------------------

### Verify imsg installation

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

Checks the installed version and lists recent chats. If chats returns 'unable to open database file' or 'authorization denied', the CLI is installed correctly but macOS hasn't granted Full Disk Access yet.

```bash
imsg --version
imsg chats --limit 3
```

--------------------------------

### Install imsg via Homebrew and check version

Source: https://github.com/openclaw/imsg/blob/main/README.md

Install imsg on macOS using Homebrew, then verify the installation. Requires macOS 14 or newer.

```bash
brew install steipete/tap/imsg
imsg --version
```

--------------------------------

### Zsh completions installation

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

Creates the completions directory and generates the zsh completion script. Requires `~/.zsh/completions` on `fpath` and `compinit` to be called.

```bash
mkdir -p ~/.zsh/completions
imsg completions zsh > ~/.zsh/completions/_imsg
```

--------------------------------

### Pick a target chat with imsg chats

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

List chats as JSON and extract the GUID and display name/identifier. Then set the CHAT environment variable to the chosen chat's GUID.

```bash
imsg chats --limit 10 --json | jq -r '"\(.guid)\t\(.name // .identifier)"'
export CHAT='iMessage;-;+15551234567'    # paste guid from above
```

--------------------------------

### Install imsg Linux archive from GitHub releases

Source: https://github.com/openclaw/imsg/blob/main/docs/linux.md

Download and extract the latest imsg-linux-x86_64.tar.gz release archive, then run imsg. The archive is published for releases 0.8.0 and newer.

```bash
curl -LO https://github.com/openclaw/imsg/releases/latest/download/imsg-linux-x86_64.tar.gz
tar -xzf imsg-linux-x86_64.tar.gz
./imsg chats --db ./chat.db --limit 5
```

--------------------------------

### Run imsg debug build with arguments

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

Clean debug rebuild that runs the resulting binary with the supplied arguments. Useful for day-to-day development.

```bash
make imsg ARGS="chats --limit 5"
```

--------------------------------

### Development make commands

Source: https://github.com/openclaw/imsg/blob/main/README.md

Run lint, test, and build targets for the project. `make lint` treats formatting and lint findings as errors.

```bash
make lint
make test
make build

```

--------------------------------

### Bash completions installation

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

Generates a bash completion script and redirects it to the user's or system-wide bash completion directory. Reload the shell to activate tab-completion.

```bash
imsg completions bash > ~/.bash_completion.d/imsg
# or, system-wide:
sudo imsg completions bash > /usr/local/etc/bash_completion.d/imsg
```

--------------------------------

### Stream JSON output with jq and use RPC/completions

Source: https://github.com/openclaw/imsg/blob/main/README.md

Use `--json` to emit one JSON object per line; pipe finite commands through `jq -s` to collect them into a single array. `imsg rpc` starts the long-running stdio transport for agents and gateways, and `imsg completions llm` provides shell completions.

```bash
imsg chats --json | jq -s
```

```bash
imsg rpc
```

```bash
imsg completions llm
```

--------------------------------

### Install bridge login agent with imsg launch --install-agent

Source: https://github.com/openclaw/imsg/blob/main/docs/troubleshooting.md

Installs the opt-in bridge login agent that restores bridge injection at login and checks it periodically. Intended for a dedicated bridge Mac with SIP disabled.

```bash
imsg launch --install-agent
```

--------------------------------

### status method response example

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Example JSON response for the status method, showing the readiness snapshot including database, bridge, contacts, and method lists.

```json
{
  "version": "0.x.y",
  "protocol_version": 1,
  "database": {
    "path": "/Users/me/Library/Messages/chat.db",
    "ready": true,
    "features": {
      "unread_state": true,
      "scheduled_messages": true,
      "reactions": true,
      "reply_context": true,
      "routing_metadata": true,
      "balloon_payloads": true
    }
  },
  "bridge": {
    "ready": false,
    "error": "The bridge is not started. Run imsg launch explicitly before using bridge methods."
  },
  "contacts": { "available": true },
  "methods": ["initialize", "status", "watch.unsubscribe", "chats.list", "chats.get", "send", "typing", "read"],
  "supported_methods": ["initialize", "status", "watch.unsubscribe", "..."]
}
```

--------------------------------

### Check imsg version

Source: https://github.com/openclaw/imsg/blob/main/docs/troubleshooting.md

Run this command to display the installed imsg version, useful when filing an issue.

```bash
imsg --version
```

--------------------------------

### Generate LLM Markdown reference

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

Emits a Markdown CLI reference documenting every command, flag, argument, and example. Designed for embedding in an agent's system prompt or tool documentation index.

```bash
imsg completions llm
```

--------------------------------

### Run imsg stats with options

Source: https://github.com/openclaw/imsg/blob/main/docs/stats.md

Basic invocation of `imsg stats` with no options, followed by examples using `--time-zone`, `--json`, `--chat-id`, and `--media`. The default timezone is the process's local timezone; pass an IANA identifier with `--time-zone`. `--chat-id` scopes every message and media dimension, and the rowid must be positive and exist in the selected database.

```bash
imsg stats
imsg stats --time-zone Europe/Vienna --json
imsg stats --chat-id 42 --media --json
```

--------------------------------

### Uninstall imsg via Homebrew

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

Removes the imsg binary and optionally removes the tap. The untap command is optional.

```bash
brew uninstall imsg
brew untap steipete/tap   # optional
```

--------------------------------

### History with date window using --start and --end

Source: https://github.com/openclaw/imsg/blob/main/docs/history.md

Filters messages to a date range. Both bounds accept ISO 8601 with explicit timezone and are optional. The limit applies after filtering, so --limit 20 --start ... returns up to 20 messages from inside the window.

```bash
imsg history --chat-id 42 \
  --start 2026-05-01T00:00:00Z \
  --end   2026-05-06T00:00:00Z \
  --json
```

--------------------------------

### chats.get result example

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Example JSON result for the chats.get method, showing the metadata object for a chat.

```json
{
  "id": 42,
  "identifier": "chat123",
  "guid": "iMessage;+;chat123",
  "name": "Group Chat",
  "service": "iMessage",
  "is_group": true,
  "participants": ["+14155551212", "+14155551213"]
}
```

--------------------------------

### Build imsg from source

Source: https://github.com/openclaw/imsg/blob/main/docs/install.md

Requires Swift 6.1 or newer (Xcode 16.3 or newer) on macOS. Runs the universal release build through Swift Package Manager, applies required SQLite.swift and PhoneNumberKit resource patches, and places the binary at bin/imsg.

```bash
git clone https://github.com/openclaw/imsg.git
cd imsg
make build
./bin/imsg --help
```

--------------------------------

### History with only start or only end bound

Source: https://github.com/openclaw/imsg/blob/main/docs/history.md

Shows how to use a single bound. An end date in year 9999 includes all stored dates, while a start date in that year returns no messages.

```bash
# Everything since May 1st.
imsg history --chat-id 42 --start 2026-05-01T00:00:00Z --json
```

```bash
# Everything before May 6th.
imsg history --chat-id 42 --end 2026-05-06T00:00:00Z --json
```

--------------------------------

### Run common imsg commands with JSON output

Source: https://github.com/openclaw/imsg/blob/main/docs/index.md

Shows a set of one-liner commands for listing chats, reading history, getting stats, inspecting scheduled messages and chat backgrounds, streaming new messages, and sending text or files. All commands use --json for newline-delimited JSON output on stdout, while human progress and warnings go to stderr.

```bash
# List the 10 most recent chats.
imsg chats --limit 10 --json | jq -s

# Read history from one chat, with attachment metadata.
imsg history --chat-id 42 --limit 20 --attachments --json

# Summarize logical message and media counts.
imsg stats --time-zone Europe/Vienna --media --json

# Inspect future Send Later rows without launching Messages.
imsg scheduled list --json

# Inspect local chat-background metadata without launching Messages.
imsg chat-background status --chat-id 42 --json

# Stream new messages live, including tapbacks.
imsg watch --chat-id 42 --reactions --json

# Send a message — auto-pick iMessage or SMS.
imsg send --to "+14155551212" --text "on my way"

# Send a file (image, audio, document).
imsg send --to "Jane Appleseed" --file ~/Desktop/voice.m4a
```

--------------------------------

### Check imsg binary location and Homebrew version

Source: https://github.com/openclaw/imsg/blob/main/docs/troubleshooting.md

Run these commands to diagnose a version mismatch between the installed imsg binary and the Homebrew formula. If `which imsg` does not point to the Homebrew prefix, remove the older binary or reorder your PATH.

```bash
which imsg
brew list --versions imsg
```

--------------------------------

### imsg notify-anyways

Source: https://github.com/openclaw/imsg/blob/main/docs/bridge.md

Sends a notification for an existing message in a chat. Requires the chat identifier and the message GUID.

```APIDOC
## [CLI] imsg notify-anyways

### Description
Sends a notification for an existing message in a chat.

### Command
`imsg notify-anyways`

### Parameters
- `--chat` (string) - Required - The chat identifier (e.g., `'iMessage;-;+15551234567'`).
- `--message` (string) - Required - The GUID of the message to notify about.

### Example
```bash
imsg notify-anyways --chat 'iMessage;-;+15551234567' --message <message-guid>
```
```

--------------------------------

### Check Messages chat.db existence

Source: https://github.com/openclaw/imsg/blob/main/docs/troubleshooting.md

Run this command to verify that the Messages database exists. If the file is missing, open Messages.app and complete iMessage / SMS Forwarding setup; the database is created lazily on first sign-in.

```bash
ls -la ~/Library/Messages/chat.db
```

--------------------------------

### Read, watch, and send iMessage with imsg CLI

Source: https://github.com/openclaw/imsg/blob/main/README.md

Shows core imsg commands for reading chats, fetching history with attachments, watching for updates with reactions, and sending a message via Messages.app. Output is NDJSON, suitable for piping to jq.

```bash
imsg chats --limit 10 --json | jq -s
```

```bash
imsg history --chat-id 42 --limit 20 --attachments --json | jq -s
```

```bash
imsg watch --chat-id 42 --reactions --json
```

```bash
imsg send --to "+14155551212" --text "on my way"
```

--------------------------------

### status

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Accepts no params (an explicit empty object is allowed). It retries the database open, probes only an already-running bridge, and returns no setup prose or message content.

```APIDOC
## status

### Description
Accepts no params (an explicit empty object is allowed). It retries the database open, probes only an already-running bridge, and returns no setup prose or message content.

### Parameters
No params accepted (an explicit empty object is allowed).

### Response
#### Success Response
- **version** (string) - Version of the service.
- **protocol_version** (int) - Protocol version.
- **database** (object) - Database status and features.
  - **path** (string) - Path to the database.
  - **ready** (bool) - Whether the database is ready.
  - **features** (object) - Feature-level booleans.
    - **unread_state** (bool) - Whether unread state is supported.
    - **scheduled_messages** (bool) - Whether scheduled messages are supported.
    - **reactions** (bool) - Whether reactions are supported.
    - **reply_context** (bool) - Whether reply context is supported.
    - **routing_metadata** (bool) - Whether routing metadata is supported.
    - **balloon_payloads** (bool) - Whether balloon payloads are supported.
- **bridge** (object) - Bridge status.
  - **ready** (bool) - Whether the bridge is ready.
  - **error** (string) - Error message if bridge is not ready.
- **contacts** (object) - Contacts availability.
  - **available** (bool) - Whether contacts are available.
- **methods** (array of strings) - Structurally usable surface at that instant.
- **supported_methods** (array of strings) - Compiled union for protocol negotiation.

#### Response Example
```json
{
  "version": "0.x.y",
  "protocol_version": 1,
  "database": {
    "path": "/Users/me/Library/Messages/chat.db",
    "ready": true,
    "features": {
      "unread_state": true,
      "scheduled_messages": true,
      "reactions": true,
      "reply_context": true,
      "routing_metadata": true,
      "balloon_payloads": true
    }
  },
  "bridge": {
    "ready": false,
    "error": "The bridge is not started. Run imsg launch explicitly before using bridge methods."
  },
  "contacts": { "available": true },
  "methods": ["initialize", "status", "watch.unsubscribe", "chats.list", "chats.get", "send", "typing", "read"],
  "supported_methods": ["initialize", "status", "watch.unsubscribe", "..."]
}
```
```

--------------------------------

### Use --json with jq and watch

Source: https://github.com/openclaw/imsg/blob/main/docs/json.md

Every read command supports --json, emitting newline-delimited JSON (NDJSON). The examples pipe chats and history through jq -s to materialize an array, while watch streams NDJSON directly. Human progress, prompts, and warnings go to stderr, keeping stdout parseable.

```bash
imsg chats --json | jq -s
```

```bash
imsg history --chat-id 42 --json | jq -s
```

```bash
imsg watch --chat-id 42 --json
```

--------------------------------

### imsg send service selection examples

Source: https://github.com/openclaw/imsg/blob/main/docs/send.md

Shows the default auto service, forced iMessage, forced SMS, and disabling SMS fallback. The auto mode checks chat.db history; imessage fails fast if the recipient isn't on iMessage; sms requires Text Message Forwarding. SMS fallback is not used for explicit service choices, chat-target sends, email, attachments, or groups.

```bash
imsg send --to "+14155551212" --text "hi" --service auto       # default
imsg send --to "+14155551212" --text "hi" --service imessage
imsg send --to "+14155551212" --text "hi" --service sms
imsg send --to "+14155551212" --text "hi" --no-sms-fallback
```

--------------------------------

### send.sticker request JSON

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Request to send a validated image file as a sticker-attributed IMCore transfer. Requires the bridge to be injected with `imsg launch`; AppleScript cannot preserve sticker attribution. Use exactly one of `chat_id`, `chat_identifier`, or `chat_guid`. `attach_to` accepts a bare message GUID or `p:N/GUID`; `part_index` must agree with an embedded part and is invalid without `attach_to`. Unknown parameters and non-object params fail with invalid params.

```json
{"jsonrpc":"2.0","id":"sticker","method":"send.sticker","params":{"chat_id":42,"file":"~/Desktop/sticker.png","attach_to":"MESSAGE_GUID","part_index":0}}
```

--------------------------------

### List chats and read history with imsg

Source: https://github.com/openclaw/imsg/blob/main/README.md

Find a chat id with `imsg chats --limit 3`, then read its ten most recent messages with `imsg history --chat-id 42 --limit 10`. Replace `42` with an id from the first command. Requires Full Disk Access to read `~/Library/Messages/chat.db`.

```bash
# Find a chat and note its id.
imsg chats --limit 3

# Read its ten most recent messages.
imsg history --chat-id 42 --limit 10
```

--------------------------------

### Zsh configuration for completions

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

Standard `~/.zshrc` snippet to add the completions directory to `fpath` and initialize `compinit`.

```zsh
fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinit
```

--------------------------------

### chats.list result example

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Example JSON result for the chats.list method, showing the structure with a chats array.

```json
{ "chats": [Chat] }
```

--------------------------------

### Reload bridge helper after build (imsg launch --kill-only, --dylib, status)

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Commands to stop the bridge and reload the rebuilt helper dylib, then check status. launch alone reuses a ready bridge; stopping it first ensures the rebuilt helper is loaded. Do not type the addresses in Messages between the old and new runs.

```bash
./bin/imsg launch --kill-only
./bin/imsg launch --dylib "$(pwd)/bin/imsg-bridge-helper.dylib"
./bin/imsg status --json
```

--------------------------------

### Copy chat.db from macOS using SQLite backup

Source: https://github.com/openclaw/imsg/blob/main/docs/linux.md

Use SQLite's backup command to create a consistent snapshot of the live chat.db, then verify it with pragma quick_check. Do not use plain cp on a live database.

```bash
mkdir -p /tmp/imsg-linux
sqlite3 "$HOME/Library/Messages/chat.db" \
  ".backup '/tmp/imsg-linux/chat.db'"
sqlite3 /tmp/imsg-linux/chat.db 'pragma quick_check;'
```

--------------------------------

### Create chat and manage members (imsg chat-create, chat-add-member, chat-name, chat-photo, chat-remove-member, chat-leave)

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Commands to create a chat with two addresses, capture the chatGuid, add a member, rename, set photo, remove member, and leave. chat-create is iMessage-only; use imsg send --service sms for SMS. Expect each step to be visible in Messages.app within a second or two.

```bash
imsg chat-create --addresses '+15551111111,+15552222222' \
  --name 'imsg test' --text 'hello' --json
# Capture the new chatGuid from the JSON output:
export GROUP=<paste chatGuid>
imsg chat-add-member --chat "$GROUP" --address +15553333333
imsg chat-name --chat "$GROUP" --name 'imsg test renamed'
imsg chat-photo --chat "$GROUP" --file ~/Pictures/test.jpg
imsg chat-remove-member --chat "$GROUP" --address +15553333333
imsg chat-leave --chat "$GROUP"
```

--------------------------------

### imsg delete-message

Source: https://github.com/openclaw/imsg/blob/main/docs/bridge.md

Deletes an existing message from a chat. Requires the chat identifier and the message GUID.

```APIDOC
## [CLI] imsg delete-message

### Description
Deletes an existing message from a chat.

### Command
`imsg delete-message`

### Parameters
- `--chat` (string) - Required - The chat identifier (e.g., `'iMessage;-;+15551234567'`).
- `--message` (string) - Required - The GUID of the message to delete.

### Example
```bash
imsg delete-message --chat 'iMessage;-;+15551234567' --message <message-guid>
```
```

--------------------------------

### Verify copied database on Linux

Source: https://github.com/openclaw/imsg/blob/main/docs/linux.md

After transferring the backup to Linux, run imsg chats to confirm the database is readable. Keep copied databases in a private, ignored directory and avoid printing raw message output in CI logs.

```bash
imsg chats --db ./chat.db --limit 5 --json | jq -s
```

--------------------------------

### imsg unsend

Source: https://github.com/openclaw/imsg/blob/main/docs/bridge.md

Un-sends (recalls) an existing message in a chat. Requires the chat identifier and the message GUID.

```APIDOC
## [CLI] imsg unsend

### Description
Un-sends (recalls) an existing message in a chat.

### Command
`imsg unsend`

### Parameters
- `--chat` (string) - Required - The chat identifier (e.g., `'iMessage;-;+15551234567'`).
- `--message` (string) - Required - The GUID of the message to unsend.

### Example
```bash
imsg unsend --chat 'iMessage;-;+15551234567' --message <message-guid>
```
```

--------------------------------

### imsg edit

Source: https://github.com/openclaw/imsg/blob/main/docs/bridge.md

Edits the text of an existing message in a chat. Requires the chat identifier and the message GUID.

```APIDOC
## [CLI] imsg edit

### Description
Edits the text of an existing message in a chat.

### Command
`imsg edit`

### Parameters
- `--chat` (string) - Required - The chat identifier (e.g., `'iMessage;-;+15551234567'`).
- `--message` (string) - Required - The GUID of the message to edit.
- `--new-text` (string) - Required - The new text for the message.

### Example
```bash
imsg edit --chat 'iMessage;-;+15551234567' --message <message-guid> --new-text "actually..."
```
```

--------------------------------

### Build imsg from source on Linux

Source: https://github.com/openclaw/imsg/blob/main/docs/linux.md

Build imsg on Linux with Swift 6.2 or newer. The script generates version info, resolves dependencies, patches dependencies, builds, and extracts the archive. The archive includes the static Swift runtime and dependency resources.

```bash
git clone https://github.com/openclaw/imsg.git
cd imsg
scripts/generate-version.sh
swift package resolve
scripts/patch-deps.sh
scripts/build-linux.sh
mkdir -p /tmp/imsg-linux
tar -xzf dist/imsg-linux-x86_64.tar.gz -C /tmp/imsg-linux
/tmp/imsg-linux/imsg chats --db ./chat.db --limit 5
```

--------------------------------

### Extend launch ready timeout with IMSG_LAUNCH_READY_TIMEOUT

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Set `IMSG_LAUNCH_READY_TIMEOUT` to a positive number of seconds (capped at 600) to extend the 15-second default wait for the bridge-ready file. Invalid or non-positive values use the default. A timeout still returns an error; check `imsg status` before relaunching. The setting does not bypass SIP or permission checks.

```bash
IMSG_LAUNCH_READY_TIMEOUT=60 imsg launch --json
```

--------------------------------

### Send files and audio attachments

Source: https://github.com/openclaw/imsg/blob/main/docs/send.md

Send files or audio attachments using --file, optionally with --text. Files are staged under ~/Library/Messages/Attachments/imsg/ before being handed to Messages. Attachment-only sends may wait up to eight seconds for the staged file to appear.

```bash
imsg send --to "+14155551212" --text "see attached" --file ~/Desktop/note.pdf
```

```bash
imsg send --to "Jane Appleseed" --file ~/Desktop/voice.m4a
```

```bash
imsg send --chat-id 42 --file ~/Desktop/screenshot.png
```

--------------------------------

### message.send_status

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Queries the send status of an outgoing message by its GUID. Returns normalized send state and detailed status fields.

```APIDOC
## message.send_status

### Description
Queries the send status of an outgoing message by its GUID. Returns normalized send state and detailed status fields.

### Method
RPC

### Endpoint
message.send_status

### Parameters
#### Request Body
- **guid** (string) - Required - Outgoing message GUID.

### Response
#### Success Response
- **ok** (boolean) - Indicates success.
- **guid** (string) - The message GUID.
- **send_state** (string) - Normalized to `pending`, `sent`, `delivered`, or `failed`.
- **service** (string) - The service used (e.g., iMessage).
- **checked_at** (string) - Timestamp when the status was checked.
- **delivered_at** (string) - Timestamp when the message was delivered.
- **status_fields** (object) - Detailed status fields.
  - **is_sent** (boolean) - Whether the message was sent.
  - **is_delivered** (boolean) - Whether the message was delivered.
  - **is_finished** (boolean) - Whether the message is finished.
  - **error** (integer) - Error code.
  - **date_delivered** (string) - Delivery timestamp.
  - **date_read** (string or null) - Read timestamp.
  - **is_delayed** (boolean) - Whether delivery is delayed.
  - **is_prepared** (boolean) - Whether the message is prepared.
  - **is_pending_satellite_send** (boolean) - Whether pending satellite send.
  - **was_downgraded** (boolean) - Whether the message was downgraded.

#### Response Example
```json
{
  "ok": true,
  "guid": "8DF...",
  "send_state": "delivered",
  "service": "iMessage",
  "checked_at": "2026-05-28T20:43:00Z",
  "delivered_at": "2026-05-28T20:42:58Z",
  "status_fields": {
    "is_sent": true,
    "is_delivered": true,
    "is_finished": true,
    "error": 0,
    "date_delivered": "2026-05-28T20:42:58Z",
    "date_read": null,
    "is_delayed": false,
    "is_prepared": false,
    "is_pending_satellite_send": false,
    "was_downgraded": false
  }
}
```

### Notes
- Missing rows return `pending` with `status_fields: null`.
```

--------------------------------

### Generate tone.mp3 and base64 encode with ffmpeg and base64

Source: https://github.com/openclaw/imsg/blob/main/Tests/IMsgCoreTests/Fixtures/README.md

Creates a 0.5-second 440 Hz stereo MP3 at 32 kbit/s and encodes it to base64. The resulting tone.mp3.base64 is used by tests; tests do not require ffmpeg.

```sh
ffmpeg -f lavfi -i 'sine=frequency=440:sample_rate=44100:duration=0.5' \
  -ac 2 -c:a libmp3lame -b:a 32k -map_metadata -1 -write_xing 0 tone.mp3
base64 -i tone.mp3 -o tone.mp3.base64
```

--------------------------------

### Manage chats and participants with imsg chat-create, chat-name, chat-photo, chat-add-member, chat-remove-member, chat-leave, chat-delete, chat-mark

Source: https://github.com/openclaw/imsg/blob/main/docs/bridge.md

Use these commands to create, rename, set a photo, add/remove members, leave, delete, or mark a chat. chat-photo clears the photo when --file is omitted. chat-mark also accepts --unread. chat-create creates iMessage chats; SMS sending remains available through the standard 'imsg send --service sms' path.

```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 ~/Pictures/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
```

--------------------------------

### initialize

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Returns the same readiness snapshot as status. It is optional, idempotent, and may be called at any time; it does not establish session state.

```APIDOC
## initialize

### Description
Returns the same readiness snapshot as `status`. It is optional, idempotent, and may be called at any time; it does not establish session state.

### Parameters
#### Params
- **protocol_version** (int, optional) — when supplied, must be `1`.

### Errors
Unknown params and unsupported versions return invalid params.
```

--------------------------------

### send

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Sends a message to a recipient. Supports multiple transports: auto, bridge, or applescript. Returns a confirmation with transport, message ID, and GUID.

```APIDOC
## send

### Description
Sends a message to a recipient. Supports multiple transports: auto, bridge, or applescript. Returns a confirmation with transport, message ID, and GUID.

### Method
RPC

### Endpoint
send

### Parameters
#### Params
- **to** (string) - Required - The recipient address (e.g., phone number).
- **text** (string) - Required - The message text.
- **transport** (string) - Optional - One of "auto", "bridge", or "applescript". Defaults to "auto".

### Request Example
```json
{"jsonrpc":"2.0","id":"3","method":"send","params":{"to":"+14155551212","text":"hi"}}
```

### Response
#### Success Response
- **ok** (boolean) - Whether the send succeeded.
- **transport** (string) - The transport used.
- **id** (integer) - The message ID.
- **guid** (string) - The message GUID.

#### Response Example
```json
{"jsonrpc":"2.0","id":"3","result":{"ok":true,"transport":"applescript","id":1979,"guid":"8DF..."}}
```
```

--------------------------------

### Prerequisites: disable SIP and build/launch imsg

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Disable System Integrity Protection in Recovery mode, then build and launch imsg with the dylib injected. Verify the bridge version with 'imsg status'.

```bash
# In Recovery mode
csrutil disable

# Back in normal boot:
make build && make build-dylib
imsg launch                 # kills + relaunches Messages with DYLD_INSERT
imsg status                 # expect: bridge version: v2 (v2 inbox active)
```

--------------------------------

### imsg read

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Marks the chat for a given handle as read, clearing the unread counter in Messages without spawning a UI action. Supports specifying the chat by ID, identifier, or GUID.

```APIDOC
## [CLI] imsg read

### Description
Marks the chat for that handle as read. Useful when you want a programmatic agent to clear the unread counter in Messages without spawning a UI action.

### Method
CLI command

### Endpoint
`imsg read`

### Parameters
#### Options
- `--to` (string) - Required - The phone number or handle of the chat to mark as read.
- `--chat-id` (integer) - Optional - The chat ID to mark as read.
- `--chat-identifier` (string) - Optional - The chat identifier to mark as read.
- `--chat-guid` (string) - Optional - The chat GUID to mark as read.

### Request Example
```bash
imsg read --to "+14155551212"
imsg read --to "+14155551212" --chat-id 42
imsg read --to "+14155551212" --chat-identifier "iMessage;+;chat..."
imsg read --to "+14155551212" --chat-guid "iMessage;+;chat..."
```

### Response
No response body is documented.
```

--------------------------------

### Launch Messages with injected dylib and confirm bridge status

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Run `imsg launch` to inject the helper dylib into Messages.app and `imsg status` to confirm the bridge is up. `imsg launch` refuses to inject when SIP is enabled; there is no override. `imsg status` is read-only and does not auto-launch or auto-inject.

```bash
imsg launch        # launches Messages.app with the dylib injected
imsg status        # confirms the bridge is up
```

--------------------------------

### Inspect account, local history, and address capabilities

Source: https://github.com/openclaw/imsg/blob/main/docs/bridge.md

Use these commands to inspect the active account, local history, and address capabilities. The `--local` flag returns your AddressBook label instead of bridge data. `nickname --json` reads the correspondent's shared Messages Name & Photo; its result includes `address`, `has_nickname`, and `description`, plus optional fields like `first_name`, `last_name`, `display_name`, `avatar_path`, and `avatar_is_sensitive`. Missing fields are omitted; `avatar_path` is a local Messages cache path, not a downloaded image.

```bash
imsg account
imsg account --local
imsg whois --address +15551234567 --type phone
imsg whois --address +15551234567 --local
imsg nickname --address +15551234567
imsg nickname --address +15551234567 --local
```

--------------------------------

### Send to group chat with --chat-identifier or --chat-guid

Source: https://github.com/openclaw/imsg/blob/main/docs/send.md

Use --chat-identifier or --chat-guid when only the portable handles are available. Both commands target the same group chat using the portable handle string.

```bash
imsg send --chat-identifier "iMessage;+;chat1234567890" --text "hi"
```

```bash
imsg send --chat-guid "iMessage;+;chat1234567890" --text "hi"
```

--------------------------------

### handles.check result JSON

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Example result from the handles.check RPC, which requires the IMCore bridge. The address is a phone number or email; alias_type is inferred when omitted, and SMS checks are rejected.

```json
{
  "ok": true,
  "address": "+14155551212",
  "alias_type": "phone",
  "destination": "tel:+14155551212",
  "id_status": 1,
  "available": true,
  "service": "iMessage"
}
```

--------------------------------

### send.tracked

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Sends exactly one text message through the already-running IMCore bridge with a caller-owned message GUID. This method never falls back to AppleScript and never retries after an uncertain bridge result.

```APIDOC
## send.tracked

### Description
Sends exactly one text message through the already-running IMCore bridge with a caller-owned message GUID. This method never falls back to AppleScript and never retries after an uncertain bridge result.

### Method
RPC

### Endpoint
send.tracked

### Parameters
#### Request Body
- **attempt_id** (UUID string) - Required - Becomes the outgoing `IMMessage` GUID.

### Notes
- Attachments are rejected.
- The method is advertised by `imsg status --json` only when the running injected helper reports caller-owned GUID preservation and reservation support; the RPC method is usable only while the Messages database is also readable.
- IDs already present in message history or reserved by another tracked send are rejected before dispatch.
- On success, `attempt_id`, `guid`, and `message_id` all identify the exact same message.
- If the RPC response is lost, query `message.send_status` with that UUID instead of matching message history by recipient, text, or timestamp.
- The UUID is a correlation marker, not authorization to read or mutate a message.
- Direct `to` sends and explicit `chat_identifier` / `chat_guid` targets remain usable while the database is down. In that state `send` skips history-based service inference, direct-chat lookup, and post-send row verification, then returns only fields observable from the chosen transport. A `chat_id` target always requires the database and returns `-32002` while it is unavailable.
- Bridge text sends resolve a bare `chat_identifier` by exact identifier or known GUID prefix, including groups whose GUID starts with `any;+;`. A missing chat is rejected before dispatch with `disposition: "not_started"` and `retry_safe: true`; a successful result reports the resolved `chat_guid`. Explicit service-qualified GUIDs never fall through to a different service.
- For chat-target sends, `send` also performs the Tahoe ghost-row check: if Messages writes an empty unjoined SMS row instead of delivering, the call returns an error rather than `{"ok": true}`.
```

--------------------------------

### Sanity-check: list recent chats

Source: https://github.com/openclaw/imsg/blob/main/docs/quickstart.md

Verify Full Disk Access is granted by listing the three most recent conversations. If this fails, see the Permissions page.

```bash
imsg chats --limit 3
```

--------------------------------

### send.sticker response JSON

Source: https://github.com/openclaw/imsg/blob/main/docs/rpc.md

Successful response from `send.sticker`. `transfer_guid` is returned on every successful bridge send. `guid` and `message_id` are included when Messages exposes the newly queued message immediately; treat them as best-effort.

```json
{"ok":true,"transfer_guid":"..."}
```

--------------------------------

### Send Apple URL preview with imsg send-rich

Source: https://github.com/openclaw/imsg/blob/main/docs/bridge.md

Sends an Apple URL preview. URL mode cannot be combined with text, effects, replies, or files.

```bash
imsg send-rich --chat 'iMessage;-;+15551234567' --url https://imsg.sh
```

--------------------------------

### Save LLM reference to file

Source: https://github.com/openclaw/imsg/blob/main/docs/completions.md

Redirects the LLM reference to a file for embedding in an agent's tool description, prompt, or memory.

```bash
imsg completions llm > /tmp/imsg-help.md
# Embed /tmp/imsg-help.md in your agent's tool description, prompt, or memory.
```

--------------------------------

### Mutate an existing message with imsg edit, unsend, delete-message, notify-anyways

Source: https://github.com/openclaw/imsg/blob/main/docs/bridge.md

Use these commands to edit, unsend, delete, or force-notify an existing message. Replace <message-guid> with the message's GUID. The chat identifier uses the format 'iMessage;-;+15551234567'.

```bash
imsg edit --chat 'iMessage;-;+15551234567' \
  --message <message-guid> --new-text "actually..."
imsg unsend --chat 'iMessage;-;+15551234567' --message <message-guid>
imsg delete-message --chat 'iMessage;-;+15551234567' --message <message-guid>
imsg notify-anyways --chat 'iMessage;-;+15551234567' --message <message-guid>
```

--------------------------------

### Cleanup: un-inject Messages and re-enable SIP

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Kill Messages to un-inject and restore normal launch behavior. Re-enable SIP in Recovery with csrutil enable when done testing.

```bash
killall Messages              # un-inject; next launch is normal
csrutil enable                # in Recovery, re-enable SIP when done
```

--------------------------------

### Inspect one chat with imsg group

Source: https://github.com/openclaw/imsg/blob/main/docs/chats.md

Returns chat details including identifier, GUID, service, participants, group/direct flag, and account routing hints. Works for direct chats despite the name. Use before scripting a send.

```bash
imsg group --chat-id 42
imsg group --chat-id 42 --json
```

--------------------------------

### Show or hide typing indicator with imsg typing

Source: https://github.com/openclaw/imsg/blob/main/docs/advanced-imcore.md

Displays or hides the 'typing' bubble on the recipient's device. --service accepts imessage, sms, or auto. On macOS 26, typing indicators frequently fail with an entitlement error, reported as an advanced-feature setup error.

```bash
imsg typing --to "+14155551212" --duration 5s
imsg typing --to "+14155551212" --duration 30s --service imessage
imsg typing --to "+14155551212" --stop true
```

--------------------------------

### Stream messages including reactions

Source: https://github.com/openclaw/imsg/blob/main/docs/quickstart.md

Watch a chat and include tapbacks (reactions) in the JSON output.

```bash
imsg watch --chat-id 42 --reactions --json
```

--------------------------------

### Cast a vote on a native poll with imsg poll vote

Source: https://github.com/openclaw/imsg/blob/main/docs/history.md

Votes on an existing poll using a 1-based `--option-index`. `imsg` resolves the index to the poll's stable option identifier before sending. Requires the poll GUID from `imsg history` or `imsg watch`.

```bash
imsg poll vote --chat-id <id> --poll <poll-guid> --option-index 2
```

--------------------------------

### Filter history JSON for poll rows with jq

Source: https://github.com/openclaw/imsg/blob/main/docs/history.md

Use with `imsg history --chat-id 42 --json` to extract rows that have a `poll` field. The output includes `id`, `guid`, and the full `poll` object, which may contain `kind`, `question`, `options`, `original_guid`, and `votes`.

```bash
imsg history --chat-id 42 --json \
  | jq -c 'select(.poll != null) | {id, guid, poll}'
```

--------------------------------

### Introspection commands: imsg account, whois, nickname

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Use imsg account to show account info, imsg whois with --address and --type phone to look up a phone number, and imsg nickname to set or view a nickname for an address.

```bash
imsg account
imsg whois --address +15551234567 --type phone
imsg nickname --address +15551234567
```

--------------------------------

### Stream one chat with imsg watch --chat-id

Source: https://github.com/openclaw/imsg/blob/main/docs/watch.md

Filters to a single chat by its ID. The --chat-id filter preserves the requested chat's context. For more advanced filtering, use --participants, --start, and --end, which mirror the history command.

```bash
imsg watch --chat-id 42 --json
```

--------------------------------

### Stream typing events with imsg watch --bb-events --json

Source: https://github.com/openclaw/imsg/blob/main/Tests/imsgTests/README-live.md

Run imsg watch in the background to emit started-typing and stopped-typing JSON objects when typing occurs in a conversation. Use kill %1 to stop the background process.

```bash
imsg watch --bb-events --json &
# from another device or simulator, type into your conversation
# you should see started-typing / stopped-typing JSON objects emit
kill %1
```

--------------------------------

### Send to a group with imsg send

Source: https://github.com/openclaw/imsg/blob/main/docs/groups.md

Use the most stable identifier you have: `--chat-id` (preferred, DB local), `--chat-identifier` (portable), or `--chat-guid` (portable). Group sends use AppleScript `chat id "<handle>"` (the "Jared pattern").

```bash
imsg send --chat-id 42 --text "hi"                                    # preferred (DB local)
imsg send --chat-identifier "iMessage;+;chat1234567890" --text "hi"   # portable
imsg send --chat-guid "iMessage;+;chat1234567890" --text "hi"         # portable
```

--------------------------------

### Read-only inspection commands on Linux

Source: https://github.com/openclaw/imsg/blob/main/docs/linux.md

Run these imsg commands on Linux to inspect a copied chat.db. The JSON output shape matches macOS for read paths. Use --db to point at the copied database.

```bash
imsg chats --db ./chat.db --limit 20 --json | jq -s
imsg group --db ./chat.db --chat-id 42 --json
imsg history --db ./chat.db --chat-id 42 --limit 50 --json | jq -s
imsg search --db ./chat.db --query "invoice" --limit 20 --json | jq -s
```

--------------------------------

### Check macOS version with sw_vers

Source: https://github.com/openclaw/imsg/blob/main/docs/troubleshooting.md

Run this command to display the macOS version, useful when filing an issue.

```bash
sw_vers
```
Tokens:
Raw