# 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