feat: add iMessage channel, channels setup guide, 3-way distinction

- messaging/channels-setup.md: comprehensive guide covering all 3 channels (Telegram, Discord, iMessage), bun install, plugin setup, session persistence workarounds, and enterprise admin settings - messaging/imessage-setup.md: macOS-specific iMessage setup with Full Disk Access, /imessage access allow, and known quirks - messaging/README.md: rewritten with 3-way distinction table (Channels=event-based, Dispatch=message-based, RC=direct control) - examples/12: expanded from 2 options to 3 with clear trigger model - feature-map.md: row 9 updated to include iMessage - README.md: session persistence warning added as top-level section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 10:16:53 +01:00 · 2026-03-26 10:16:53 +01:00 · b47fcdfc14
commit b47fcdfc14
parent e8a5403f91
6 changed files with 355 additions and 77 deletions
--- a/README.md
+++ b/README.md
@ -62,7 +62,7 @@ Paste the prompt from examples/01-agent-runtime/prompt.md
 | `security/` | Permission modes, Auto Mode, hook patterns, NemoClaw comparison |
 | `memory/` | How Claude Code memory works vs OpenClaw's vector search |
 | `automation/` | Cron, launchd, /loop, /schedule |
-| `messaging/` | Slack MCP, Telegram Channels, channel comparison |
+| `messaging/` | Channels (iMessage, Telegram, Discord), Slack MCP, Dispatch/RC comparison |
 | `browser/` | Playwright MCP setup and usage |
 | `cowork-integration/` | How Code + Cowork + Dispatch together replicate OpenClaw |

@ -81,7 +81,7 @@ Paste the prompt from examples/01-agent-runtime/prompt.md
 | 09 | Security Hooks | PreToolUse/PostToolUse | Exec approvals + Docker |
 | 10 | Full Pipeline | All capabilities combined | Complete workflow |
 | 11 | Computer Use | Control desktop apps | macOS/iOS/Android apps |
-| 12 | Remote Control | /rc + Dispatch (phone) | Telegram/WhatsApp control |
+| 12 | Remote Access | Channels + Dispatch + /rc (3 ways) | Telegram/WhatsApp control |
 | 13 | Auto Mode | AI safety classifier | Autonomous daemon mode |

 Each example has a self-contained prompt you can paste directly
@ -111,6 +111,15 @@ See [cowork-integration/README.md](cowork-integration/README.md)
 for a detailed breakdown of how these combine to cover OpenClaw's
 feature set.

+## The biggest practical limitation
+
+**Session persistence.** If the Claude Code session closes, all
+remote access (Channels, Dispatch, Remote Control) stops. OpenClaw
+runs as a daemon and stays alive indefinitely. Workarounds exist
+(tmux, Mac Mini, VPS), but this is an architectural difference.
+
+See `messaging/channels-setup.md` for always-on workarounds.
+
 ## The remaining gap

 **Canvas/A2UI (the only gap):** OpenClaw's canvas is an interactive
--- a/examples/12-remote-control/prompt.md
+++ b/examples/12-remote-control/prompt.md
@ -1,71 +1,115 @@
-# Example 12: Remote Control and Dispatch
+# Example 12: Remote Access (Three Ways)

-Control your Claude Code session from your phone. This is
-Anthropic's answer to OpenClaw's Telegram integration: manage
-your AI agent from anywhere.
+Control your Claude Code session from your phone. Anthropic
+now offers three distinct ways to do this, each with a
+different trigger model.

-**OpenClaw equivalent:** Telegram, WhatsApp, or any of the
-15+ messaging channels for sending commands remotely.
+**OpenClaw equivalent:** Telegram, WhatsApp, iMessage, or any
+of the 15+ messaging channels for sending commands remotely.

-## Option A: Remote Control (/rc) for Claude Code
+## The three-way distinction

-Works with the CLI. No Cowork needed.
+| Method | Trigger | Best for |
+|--------|---------|----------|
+| **Channels** | Event-based: chat apps push messages in | Reacting to messages as they arrive |
+| **Dispatch** | Message-based: you send a task | Delegating a job while away |
+| **Remote Control** | Direct control: you steer the session | Guiding work in progress |

-### Setup
+**Channels** = "my agent listens to a chat app"
+**Dispatch** = "I send my agent a job"
+**Remote Control** = "I take the wheel remotely"

-1. Start a Claude Code session in your terminal
-2. Type `/rc` (short for `/remote-control`)
-3. A URL and QR code appear
-4. Scan the QR code with your phone or open the URL in any browser
-5. You now have a full interactive session from your phone
+---

-### The prompt (from your phone)
+## Option A: Channels (Telegram, Discord, iMessage)
+
+Your agent listens to a chat app and reacts to messages.
+The closest to OpenClaw's native channel experience.
+
+### Setup (iMessage example)
+
+```bash
+# Install plugin
+/install @anthropic-ai/claude-code-imessage
+
+# Launch with channels
+claude --channels
+```
+
+### The prompt (from your phone via iMessage)

 ```
-Search the web for the latest Claude Code changelog entries,
-summarize the 3 most important features, and save the summary
-to changelog-latest.md in the project root.
+Scrape the YouTube comments from my recent video and
+give me a breakdown of the top themes and requests.
 ```

 ### What happens

- Your phone sends the message to the active CC session
- Claude Code executes on your computer (terminal stays active)
- Results appear on both your phone and the terminal
- You can continue the conversation from either device
+1. You text the message from iMessage on your phone
+2. Claude Code receives it as if you typed it locally
+3. Claude uses your skills, tools, and API keys to execute
+4. The result is sent back to you via iMessage
+5. You can approve/deny permissions from your phone

-## Option B: Dispatch for Cowork
+### Supported channels

-If you use Claude Cowork (desktop app), Dispatch lets you
-assign tasks from the Claude mobile app.
+- **Telegram** (any OS)
+- **Discord** (any OS)
+- **iMessage** (macOS only)
+
+See `messaging/channels-setup.md` for full setup details.
+
+---
+
+## Option B: Dispatch (Cowork mobile app)
+
+Send a task from the Claude mobile app. Cowork executes
+on your Mac.

 ### Setup

-1. Open Claude Desktop app on Mac
-2. Switch to Cowork mode
-3. Go to Dispatch in settings
-4. Scan QR code with Claude mobile app (iOS/Android)
-5. Your phone is now paired to your desktop agent
+1. Open Claude Desktop > Cowork mode
+2. Dispatch settings > Scan QR code with Claude mobile app
+3. Send a task from your phone

-### How it differs from /rc
+### When to use

-| Feature | /rc (Claude Code) | Dispatch (Cowork) |
-|---------|------------------|------------------|
-| Interface | Terminal session | Desktop app |
-| Requires | CLI | Cowork desktop app |
-| Phone app | Any browser | Claude mobile app |
-| Computer Use | No | Yes |
-| Connected apps | Via MCP | Built-in (Slack, Google, Notion) |
+- You want to fire-and-forget a task
+- You do not need to steer the execution
+- You want Cowork features (Computer Use, connectors)
+
+---
+
+## Option C: Remote Control (/rc)
+
+Take direct control of an active CLI session from your
+phone or any browser.
+
+### Setup
+
+```
+/rc
+```
+
+A URL and QR code appear. Scan or open from another device.
+
+### When to use
+
+- You want to guide an in-progress task
+- You need full interactive control
+- You are debugging or reviewing results live
+
+---

 ## The OpenClaw comparison

-OpenClaw lets you text your agent via Telegram, WhatsApp,
-Discord, or 12+ other channels. The agent is always-on.
+OpenClaw's 15+ native channels are always-on (daemon). All
+three Claude Code methods require an active session.

-Claude Code /rc requires an active session. Dispatch requires
-Cowork running on your Mac. Neither is truly "always-on" in
-the OpenClaw sense, but /schedule (remote triggers) can start
-sessions on demand from the web.
+**The biggest practical difference:** If the Claude Code
+session closes, all remote access stops. OpenClaw keeps
+running. Workarounds: tmux, Mac Mini, VPS.

-The gap is narrowing. For most "text my agent from my phone"
-use cases, /rc or Dispatch gets the job done.
+For most "text my agent from my phone" use cases, Channels
+or Dispatch gets the job done. The gap is the always-on
+daemon, not the phone access itself.
--- a/feature-map.md
+++ b/feature-map.md
@ -24,7 +24,7 @@ and Dispatch.
 | 6 | Computer Use | Browser + desktop app control | Computer Use in CC Desktop + Cowork (research preview) | ✅ |
 | 7 | Memory | Daily logs + vector search | CLAUDE.md hierarchy + auto-memory | ~ |
 | 8 | Multi-Agent | Sub-agents, mesh, agent-to-agent | Agent Teams, SendMessage, worktree | ✅ |
-| 9 | Messaging/Remote | 15+ native channels | MCP + Telegram (v2.1.80) + Remote Control (/rc) + Dispatch | ~ |
+| 9 | Messaging/Remote | 15+ native channels | Channels (Telegram, Discord, iMessage) + MCP + /rc + Dispatch | ~ |
 | 10 | Model Providers | 20+ providers, failover | Opus/Sonnet/Haiku + overrides | ~ |
 | 11 | Cron/Automation | HEARTBEAT.md, cron, webhooks | /loop, CronCreate, /schedule, hooks | ✅ |
 | 12 | Always-On | Daemon process, 24/7 | Headless on VPS + Cowork "keep awake" + /schedule | ~ |
--- a/messaging/README.md
+++ b/messaging/README.md
@ -2,44 +2,69 @@

 How Claude Code sends and receives messages, compared to OpenClaw.

-## OpenClaw: Native channel integrations
+## Three ways to reach Claude Code from your phone

-OpenClaw ships with 15+ channel connectors out of the box:
-Slack, Discord, Telegram, Email, SMS, WhatsApp, and others.
-Each is configured in a single YAML block. No additional setup.
+| Method | How it works | Best for |
+|--------|-------------|----------|
+| **Channels** | Chat apps push events into a running session | iMessage, Telegram, Discord |
+| **Dispatch** | Send a task from the Claude mobile app | Quick delegation |
+| **Remote Control** | Steer an active session from phone/browser | Guiding in-progress work |

-## Claude Code: MCP servers + native Telegram
+See `channels-setup.md` for the definitive guide to all three.

-Claude Code uses MCP servers for most messaging channels.
-Telegram is the exception: it has native support since v2.1.80.
+## Supported channels (native, event-based)

-### Native Telegram (no MCP needed)
+| Channel | Plugin | Platform | Since |
+|---------|--------|----------|-------|
+| Telegram | `@anthropic-ai/claude-code-telegram` | Any OS | v2.1.80 |
+| Discord | `@anthropic-ai/claude-code-discord` | Any OS | v2.1.80 |
+| iMessage | `@anthropic-ai/claude-code-imessage` | macOS only | v2.1.87 |

-Since v2.1.80, Claude Code has a Channels feature with Telegram support.
-Since v2.1.81, permission relay allows approving tool calls from your phone.
+All three follow the same pattern: install plugin, launch with
+`claude --channels`, receive and respond to messages.

-Install the Telegram plugin in Claude Code settings, connect your account,
-and Claude can send messages and wait for your approval before executing
-sensitive actions - from your phone, without opening a laptop.
+**Permission approval from phone:** When Claude needs to run a
+sensitive action, it sends a permission request through the
+channel. Reply "yes" or "no" from your phone.

-This is the closest to OpenClaw's native channel experience.
-See `telegram-channels-setup.md`.
+## MCP servers for other channels

-### MCP servers for other channels
+For channels not yet supported natively, use MCP servers:

-| Channel  | MCP Server                     | Notes                    |
-|----------|-------------------------------|--------------------------|
-| Slack    | `@modelcontextprotocol/slack` | Official MCP server      |
-| Discord  | Community MCP servers         | Search MCP registry      |
-| Email    | SMTP/IMAP MCP servers         | Several available        |
+| Channel | MCP Server | Notes |
+|---------|-----------|-------|
+| Slack | `@modelcontextprotocol/slack` | Official, well-maintained |
+| Email | SMTP/IMAP MCP servers | Several community options |

-The `.mcp.json` in this repo includes commented examples.
-See `slack-setup.md` for a complete walkthrough.
+See `slack-setup.md` for a complete Slack walkthrough.

-## Honest assessment
+## Setup guides in this directory

-OpenClaw is easier for multi-channel messaging: install once, configure in YAML,
-done. Claude Code requires setting up separate MCP servers per channel.
+| File | What it covers |
+|------|---------------|
+| `channels-setup.md` | General channels guide + Dispatch/RC comparison |
+| `imessage-setup.md` | iMessage-specific setup (macOS) |
+| `telegram-channels-setup.md` | Telegram-specific setup |
+| `slack-setup.md` | Slack via MCP server |

-For single-channel use (Telegram), Claude Code's native support is now comparable.
-For complex multi-channel workflows, OpenClaw has the advantage.
+## The critical limitation
+
+**If the Claude Code session closes, channels stop working.**
+This is the biggest practical difference from OpenClaw's
+always-on daemon. See `channels-setup.md` for workarounds
+(tmux, Mac Mini, VPS).
+
+## OpenClaw comparison
+
+OpenClaw ships with 15+ channel connectors: WhatsApp, Telegram,
+Discord, Slack, Signal, iMessage, IRC, Matrix, Teams, and more.
+Each is plug-and-play with YAML configuration.
+
+Claude Code has 3 native channels (Telegram, Discord, iMessage)
+plus MCP servers for Slack and others. The gap is narrowing but
+OpenClaw still has broader multi-channel coverage.
+
+Where Claude Code wins: security. OpenClaw's community skills
+(12% malicious per Cisco research) and CVE-2026-25253 highlight
+real risks. Claude Code's permission model and marketplace review
+process provide stronger guarantees for most users.
--- a/messaging/channels-setup.md
+++ b/messaging/channels-setup.md
@ -0,0 +1,106 @@
+# Channels Setup Guide
+
+Channels let external chat apps push messages into a running
+Claude Code session. Your agent reacts to messages as if you
+typed them locally. This is Claude Code's answer to OpenClaw's
+15+ native messaging integrations.
+
+## Supported channels (March 2026)
+
+| Channel | Plugin | Platform requirement |
+|---------|--------|---------------------|
+| Telegram | `@anthropic-ai/claude-code-telegram` | Any OS |
+| Discord | `@anthropic-ai/claude-code-discord` | Any OS |
+| iMessage | `@anthropic-ai/claude-code-imessage` | macOS only |
+
+## Prerequisites
+
+1. **Bun** (JavaScript runtime, required for channel plugins):
+   ```bash
+   curl -fsSL https://bun.sh/install | bash
+   ```
+
+2. **Full Disk Access** (macOS, required for iMessage):
+   System Settings > Privacy & Security > Full Disk Access >
+   Add your terminal app (Terminal.app or VS Code)
+
+3. **Claude Code** v2.1.80+ (channels were introduced here)
+
+## Install a channel plugin
+
+```bash
+# In a Claude Code session, run:
+/install @anthropic-ai/claude-code-telegram
+# or
+/install @anthropic-ai/claude-code-discord
+# or
+/install @anthropic-ai/claude-code-imessage
+```
+
+Verify with `/plugins` to see installed plugins.
+
+## Launch Claude Code in channel mode
+
+```bash
+claude --channels
+```
+
+You should see: `Listening for channel messages from plugin [channel-name]`
+
+Claude Code now receives messages from the configured channel
+and responds through it. Every tool, skill, and agent you have
+configured works exactly as if you were typing locally.
+
+## Permission approval from your phone
+
+When Claude Code needs to run a sensitive action, it sends a
+permission request through the channel. You can reply "yes" or
+"no" from your phone to approve or deny.
+
+To avoid constant prompts, launch with Auto Mode:
+```bash
+claude --channels --enable-auto-mode
+```
+
+## The critical limitation: session persistence
+
+**If the Claude Code session closes, the channel stops working.**
+Messages sent to the channel will not reach Claude Code until
+you start a new session with `--channels`.
+
+This is the biggest practical difference from OpenClaw, which
+runs as a daemon and stays alive indefinitely.
+
+### Workarounds for always-on
+
+| Approach | How | Reliability |
+|----------|-----|-------------|
+| tmux/screen | `tmux new -s claude && claude --channels` | Good, survives SSH disconnect |
+| Mac Mini | Dedicated machine, disable sleep | Very good |
+| macOS VPS | Cloud Mac (e.g., MacStadium, AWS EC2 Mac) | Best, but expensive |
+| /schedule | Remote triggers via claude.ai (no channel) | Different approach |
+
+For iMessage specifically, you need macOS. A Linux VPS with
+tmux works for Telegram and Discord but not iMessage.
+
+## Channels vs Dispatch vs Remote Control
+
+These three features all let you interact with Claude Code
+remotely, but they work differently:
+
+| Feature | Trigger model | Best for |
+|---------|--------------|----------|
+| **Channels** | Event-based: chat apps push messages into session | Reacting to messages, CI events, chat commands |
+| **Dispatch** | Message-based: you send a task from mobile app | Delegating work while away |
+| **Remote Control** | Direct control: you steer an active session | Guiding in-progress work from another device |
+
+**Channels** = "my agent listens to a chat app"
+**Dispatch** = "I send my agent a job"
+**Remote Control** = "I take the wheel remotely"
+
+## Enterprise and Team plans
+
+Channel use must be enabled by an admin:
+Organization Settings > Claude Code > Channels > Enable
+
+By default, channels are disabled on Team and Enterprise plans.
--- a/messaging/imessage-setup.md
+++ b/messaging/imessage-setup.md
@ -0,0 +1,94 @@
+# iMessage Channel Setup
+
+Send a text to your Claude Code session from iMessage. Claude
+reads it, executes with all your skills and tools, and texts
+back the result. Works with iMessage (blue bubbles) and SMS
+(green bubbles).
+
+**macOS only.** iMessage requires the Messages app on macOS.
+
+## Setup (5 minutes)
+
+### 1. Grant Full Disk Access
+
+System Settings > Privacy & Security > Full Disk Access >
+Add your terminal (Terminal.app, VS Code, iTerm2, etc.)
+
+This lets the plugin read the iMessage database.
+
+### 2. Install Bun
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### 3. Install the iMessage plugin
+
+In a Claude Code session:
+```
+/install @anthropic-ai/claude-code-imessage
+```
+
+Verify: `/plugins` should show the iMessage plugin as connected.
+
+### 4. Launch with channels
+
+```bash
+claude --channels
+```
+
+You should see: `Listening for channel messages from plugin iMessage`
+
+### 5. Test it
+
+Send yourself an iMessage: "Hey, can you hear me?"
+
+Claude Code should receive the message and respond through
+iMessage.
+
+## Allow other phone numbers
+
+By default, only your own number/Apple ID is allowed. To let
+others text your Claude Code:
+
+```
+/imessage access allow +1234567890
+```
+
+Or allow by Apple ID:
+```
+/imessage access allow someone@icloud.com
+```
+
+The first time a new number texts, Claude Code will ask you
+to confirm before allowing access.
+
+## Known quirk: double messages
+
+If you text yourself, every message appears twice (once as
+sender, once as receiver). Fix: text from a different number
+or Apple ID, or use the `/imessage access allow` command to
+set up a separate contact.
+
+## Tips
+
+- **Bypass permissions for unattended use:**
+  `claude --channels --dangerously-skip-permissions`
+  (Only in trusted environments. Prefer Auto Mode instead.)
+
+- **Auto Mode for safer autonomy:**
+  `claude --channels --enable-auto-mode`
+
+- **Keep session alive:** Use `tmux` or `screen` so the session
+  survives if your terminal closes.
+
+- **Skills via iMessage:** Any skill you have configured works.
+  Text "Run /daily-briefing" and your agent executes it.
+
+## Limitations
+
+- macOS only (iMessage database is a macOS feature)
+- Session must be running (no daemon mode)
+- No end-to-end encryption awareness (messages are plain text
+  to the plugin)
+- Rate limiting: Claude Code processes one message at a time