1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
# iMessage — Access & Delivery
This channel reads your Messages database (`~/Library/Messages/chat.db`) directly. Every text to this Mac — from any contact, in any chat — reaches the gate. Access control selects which conversations the assistant should see.
Texting yourself always works. **Self-chat bypasses the gate** with no setup: the server learns your own addresses at boot and lets them through unconditionally. For other senders, the default policy is **`allowlist`**: nothing passes until you add the handle with `/imessage:access allow <address>`.
All state lives in `~/.claude/channels/imessage/access.json`. The `/imessage:access` skill commands edit this file; the server re-reads it on every inbound message, so changes take effect without a restart. Set `IMESSAGE_ACCESS_MODE=static` to pin config to what was on disk at boot.
## At a glance
| | |
| --- | --- |
| Default policy | `allowlist` |
| Self-chat | Bypasses the gate; no config needed |
| Sender ID | Handle address: `+15551234567` or `someone@icloud.com` |
| Group key | Chat GUID: `iMessage;+;chat…` |
| Mention quirk | Regex only; iMessage has no structured @mentions |
| Config file | `~/.claude/channels/imessage/access.json` |
## Self-chat
Open Messages on any device signed into your Apple ID, start a conversation with yourself, and text. It reaches the assistant.
The server identifies your addresses at boot by reading `message.account` and `chat.last_addressed_handle` from `chat.db`. Messages from those addresses skip the gate entirely. To distinguish your input from its own replies — both appear in `chat.db` as from-me — it maintains a 15-second window of recently sent text and matches against it.
## DM policies
`dmPolicy` controls how texts from senders other than you, not on the allowlist, are handled.
| Policy | Behavior |
| --- | --- |
| `allowlist` (default) | Drop silently. Safe default for a personal account. |
| `pairing` | Reply with a pairing code, drop the message. Every contact who texts this Mac will receive one; only use this if very few people have the number. |
| `disabled` | Drop everything except self-chat, which always bypasses. |
```
/imessage:access policy pairing
```
## Handle addresses
iMessage identifies senders by **handle addresses**: either a phone number in `+country` format or the Apple ID email. The form matches what appears at the top of the conversation in Messages.app.
| Contact shown as | Handle address |
| --- | --- |
| Phone number | `+15551234567` (keep the `+`, no spaces or dashes) |
| Email | `someone@icloud.com` |
If the exact form is unclear, check the `chat_messages` tool output or (under `pairing` policy) the pending entry in `access.json`.
```
/imessage:access allow +15551234567
/imessage:access allow friend@icloud.com
/imessage:access remove +15551234567
```
## Groups
Groups are off by default. Opt each one in individually, keyed on the chat GUID.
Chat GUIDs look like `iMessage;+;chat123456789012345678`. They're not exposed in Messages.app; get them from the `chat_id` field in `chat_messages` tool output or from the server's stderr log when it drops a group message.
```
/imessage:access group add "iMessage;+;chat123456789012345678"
```
Quote the GUID; the semicolons are shell metacharacters.
iMessage has **no structured @mentions**. The `@Name` highlight in group chats is presentational styling — nothing in `chat.db` marks it as a mention. With the default `requireMention: true`, the only trigger is a `mentionPatterns` regex match. Set at least one pattern before opting a group in, or no message will ever match.
```
/imessage:access set mentionPatterns '["^claude\\b", "@assistant"]'
```
Pass `--no-mention` to process every message in the group, or `--allow addr1,addr2` to restrict which members can trigger it.
```
/imessage:access group add "iMessage;+;chat123456789012345678" --no-mention
/imessage:access group add "iMessage;+;chat123456789012345678" --allow +15551234567,friend@icloud.com
/imessage:access group rm "iMessage;+;chat123456789012345678"
```
## Delivery
AppleScript can send messages but cannot tapback, edit, or thread-reply; those require private API. Delivery config is correspondingly limited. Set with `/imessage:access set <key> <value>`.
**`textChunkLimit`** sets the split threshold. iMessage has no length cap; chunking is for readability. Defaults to 10000.
**`chunkMode`** chooses the split strategy: `length` cuts exactly at the limit; `newline` prefers paragraph boundaries.
There is no `ackReaction` or `replyToMode` on this channel.
## Skill reference
| Command | Effect |
| --- | --- |
| `/imessage:access` | Print current state: policy, allowlist, pending pairings, enabled groups. |
| `/imessage:access pair a4f91c` | Approve a pending code (relevant only under `pairing` policy). |
| `/imessage:access deny a4f91c` | Discard a pending code. |
| `/imessage:access allow +15551234567` | Add a handle. The primary entry point under the default `allowlist` policy. |
| `/imessage:access remove +15551234567` | Remove from the allowlist. |
| `/imessage:access policy pairing` | Set `dmPolicy`. Values: `pairing`, `allowlist`, `disabled`. |
| `/imessage:access group add "iMessage;+;chat…"` | Enable a group. Quote the GUID. Flags: `--no-mention`, `--allow a,b`. |
| `/imessage:access group rm "iMessage;+;chat…"` | Disable a group. |
| `/imessage:access set textChunkLimit 5000` | Set a config key: `textChunkLimit`, `chunkMode`, `mentionPatterns`. |
## Config file
`~/.claude/channels/imessage/access.json`. Absent file is equivalent to `allowlist` policy with empty lists: only self-chat passes.
```jsonc
{
// Handling for texts from senders not in allowFrom.
// Defaults to allowlist since this reads your personal chat.db.
// Self-chat bypasses regardless.
"dmPolicy": "allowlist",
// Handle addresses allowed to reach the assistant.
"allowFrom": ["+15551234567", "friend@icloud.com"],
// Group chats the assistant participates in. Empty object = DM-only.
"groups": {
"iMessage;+;chat123456789012345678": {
// true: respond only on mentionPatterns match.
// iMessage has no structured @mentions; regex is the only trigger.
"requireMention": true,
// Restrict triggers to these senders. Empty = any member (subject to requireMention).
"allowFrom": []
}
},
// Case-insensitive regexes that count as a mention.
// Required for groups with requireMention, since there are no structured mentions.
"mentionPatterns": ["^claude\\b", "@assistant"],
// Split threshold. No length cap; this is about readability.
"textChunkLimit": 10000,
// length = cut at limit. newline = prefer paragraph boundaries.
"chunkMode": "newline"
}
```
|