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>
This commit is contained in:
Kjell Tore Guttormsen
parent
e8a5403f91
commit
b47fcdfc14
6 changed files with 355 additions and 77 deletions
|
|
@ -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.
|
||||
|
|
|
|||
106
messaging/channels-setup.md
Normal file
106
messaging/channels-setup.md
Normal file
|
|
@ -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.
|
||||
94
messaging/imessage-setup.md
Normal file
94
messaging/imessage-setup.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue