From b47fcdfc14fe10ea428305fb8a153c00866320c3 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Thu, 26 Mar 2026 10:16:53 +0100 Subject: [PATCH] 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) --- README.md | 13 ++- examples/12-remote-control/prompt.md | 136 ++++++++++++++++++--------- feature-map.md | 2 +- messaging/README.md | 81 ++++++++++------ messaging/channels-setup.md | 106 +++++++++++++++++++++ messaging/imessage-setup.md | 94 ++++++++++++++++++ 6 files changed, 355 insertions(+), 77 deletions(-) create mode 100644 messaging/channels-setup.md create mode 100644 messaging/imessage-setup.md diff --git a/README.md b/README.md index 3977890..19bb42c 100644 --- 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 diff --git a/examples/12-remote-control/prompt.md b/examples/12-remote-control/prompt.md index dad629e..5b16457 100644 --- 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. diff --git a/feature-map.md b/feature-map.md index e1d9288..e9ea38b 100644 --- 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 | ~ | diff --git a/messaging/README.md b/messaging/README.md index 36cb90f..0ad6810 100644 --- 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. diff --git a/messaging/channels-setup.md b/messaging/channels-setup.md new file mode 100644 index 0000000..30e5ec3 --- /dev/null +++ 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. diff --git a/messaging/imessage-setup.md b/messaging/imessage-setup.md new file mode 100644 index 0000000..c5d4679 --- /dev/null +++ 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