/agent-imessage

name: agent-imessage
description: Interact with iMessage on a Mac via the imsg tool - send messages, read chats, watch for new messages
version: 2.38.0
allowed-tools: Bash(agent-imessage:*)
metadata:
  openclaw:
    requires:
      bins:
        - agent-imessage
    install:
      - kind: node
        package: agent-messenger
        bins: [agent-imessage]

Agent iMessage

An iMessage CLI for AI agents, backed by [imsg](https://github.com/openclaw/imsg) — a native macOS tool that reads the local Messages database and sends through Messages.app. Apple has no public iMessage API, so this integration runs **on a Mac** and drives Messages locally. You act as yourself with your own Apple ID; nothing leaves the machine.

Use one of these entrypoints:

• Global install: `agent-imessage ...`
• One-off execution: `bunx --package agent-messenger agent-imessage ...`

Key Concepts

• **imsg** = a local Swift CLI (`brew install steipete/tap/imsg`). `agent-imessage` spawns it and talks to it over JSON-RPC (stdin/stdout). There is **no network and no server** — it must run on the Mac signed into iMessage.
• **On-Mac only** = unlike other agent-messenger platforms, this one cannot run remotely or in a container. The agent runs on the Mac itself.
• **Permissions** = imsg needs **Full Disk Access** (to read the Messages database) and **Automation → Messages** (to send). macOS grants these to the **parent process** — the app/terminal that launches agent-messenger.
• **Chat reference** = for `message send`, a chat id (integer rowid), a portable `guid`/`identifier` (e.g. `iMessage;-;+15551234567`), or a phone/email recipient. For `message list`/`react`/`watch --chat`, prefer a **chat id** — a guid also works but (since imsg has no guid→id lookup) is resolved against the 1000 most recent chats only.
• **Watch** = streams new messages via imsg; resumable from a message rowid with `--since-rowid`.
• **Multi-account** = each account is an imsg configuration (binary path / region). Send is single-account (Messages has no from-selector).
• **Private API tier** = typing, edit/unsend, group management, custom/targeted reactions require `imsg launch` (SIP disabled). Basic send/read/watch/standard tapbacks do NOT.

Quick Start

# Guided setup: checks imsg + permissions, saves an account
agent-imessage setup

# Diagnose anytime
agent-imessage doctor

# List chats (source of chat ids/guids)
agent-imessage chat list

# Send (to a chat id, guid, or a phone/email)
agent-imessage message send 42 "Hello from agent-imessage"
agent-imessage message send "+15551234567" "Hi"

# Read recent messages
agent-imessage message list 42 --limit 20

# Watch for new messages (resumable, JSON lines)
agent-imessage message watch --chat all --jsonl

# React to the most recent incoming message (standard tapbacks)
agent-imessage message react 42 love

Setup & Permissions

iMessage runs on the Mac via imsg. One-time setup:

1. `brew install steipete/tap/imsg` 2. Sign Messages.app into your Apple ID (a dedicated Apple ID is recommended). 3. Grant **Full Disk Access** to the app/terminal launching agent-messenger (System Settings → Privacy & Security → Full Disk Access). macOS grants to the **parent process**. 4. Grant **Automation → Messages** when first prompted (needed to send).

See [setup](references/setup.md) and [permissions](references/permissions.md) references for detail.

Configuration is scriptable too:

agent-imessage auth set --bin /opt/homebrew/bin/imsg --region US --current

Environment overrides (runtime only, not persisted): `AGENT_IMESSAGE_BIN`, `AGENT_IMESSAGE_REGION`.

Agent Behavior (MANDATORY)

When a command fails, the agent MUST run `agent-imessage doctor` and act on the `suggestion`/`code` rather than telling the user to run commands. If `code` is `imsg_not_found`, guide installing imsg. If `full_disk_access` or `automation_denied`, surface the exact System Settings path (and that macOS grants to the parent process). Never silently retry the same failing call.

Commands

• `setup` — guided check + save account.
• `doctor [--account <id>] [--test-chat <chatId>]` — diagnose imsg + permissions.
• `auth set|list|use|remove|logout` — manage accounts (binary path / region).
• `chat list [--limit]` / `chat search <query> [--limit]`.
• `message list <chat> [--limit] [--start <iso>]` — read history (oldest-last). `<chat>` = chat id (recommended) or recent-chat guid.
• `message send <chat> <text>` — `<chat>` = chat id/guid or phone/email.
• `message react <chat> <reaction>` — standard tapback to the **most recent incoming** message.
• `message watch [--chat <ref|all>] [--since-rowid <n>] [--jsonl]` — stream new messages.
• `whoami` — active account + imsg status.

All commands accept `--account <id>` and `--pretty`.

Output Format

JSON by default; `--pretty` for indented output. `message watch --jsonl` emits one JSON object per line.

Feature Tiers

| Feature | Available | Requires | | --- | --- | --- | | List/search chats, send text, read/watch messages | ✅ | imsg core (no SIP) | | Standard tapbacks, to the most recent incoming message | ✅ | imsg core (no SIP) | | React to a specific message / custom-emoji tapbacks | ⏳ planned | imsg bridge (`imsg launch` + SIP) | | Typing, read receipts, edit/unsend, group management | ⏳ planned | imsg bridge (`imsg launch` + SIP) |

Error Handling

Errors are JSON with a `code` and often a `suggestion`:

| Code | Meaning | Action | | --- | --- | --- | | `imsg_not_found` | imsg binary not runnable | `brew install steipete/tap/imsg` (or set `--bin`/`AGENT_IMESSAGE_BIN`). | | `full_disk_access` | Can't read Messages DB | Grant Full Disk Access to the launching app (parent process). | | `automation_denied` | Can't control Messages | Grant Automation → Messages in System Settings. | | `not_authenticated` | No account configured | Run `agent-imessage setup`. | | `chat_not_found` | Unknown chat ref | Use a chat id/guid from `chat list`. | | `pri