Joelclaw imsg

iMessage/SMS CLI for listing chats, reading message history, watching for new messages, and sending messages. Triggers on: check messages, read imessage, send text, imsg, message history, sms, who texted me.

install

source · Clone the upstream repo

git clone https://github.com/joelhooks/joelclaw

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/joelhooks/joelclaw "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/imsg" ~/.claude/skills/joelhooks-joelclaw-imsg && rm -rf "$T"

manifest: skills/imsg/SKILL.md

iMessage

Read and send iMessages and SMS from the terminal via the

imsg

CLI.

Setup (Panda)

Messages.app signed in as: the agent Apple ID (see USER.md)
Joel's iMessage address: see USER.md →
```
imessage
```
Full Disk Access must be granted to the terminal for read operations (
```
chats
```
,
```
history
```
,
```
watch
```
)
Automation permission for Messages.app required for send
```
imsg send
```
returns
```
"sent"
```
optimistically — this means AppleScript fired, not delivery confirmed

Commands

List chats

imsg chats --limit 10 --json

Read history

imsg history --chat-id <id> --limit 20 --attachments --json

Watch for new messages

imsg watch --chat-id <id> --attachments

Send

# By email (iMessage)
imsg send --to "user@example.com" --text "hello"

# By phone number (iMessage or SMS)
imsg send --to "+18005551234" --text "hello"

# With file attachment
imsg send --to "user@example.com" --text "see attached" --file /path/to/file.jpg

Delivery Notes

```
"sent"
```
from CLI = AppleScript successfully handed off to Messages.app
"Not delivered" in Messages.app = actual delivery failure (auth issue, recipient offline, etc.)
Full Disk Access missing = read commands fail with
```
permissionDenied
```
; send still works via AppleScript
Messages appear as coming from the agent Apple ID, not from Joel

Sending to Joel

Joel's iMessage address is in USER.md (

imessage

field). Use it to notify him directly:

imsg send --to "<joel-imessage>" --text "your message"

Safety

Read-only by default — use
```
chats
```
and
```
history
```
before sending
Always confirm recipient and message text before
```
imsg send
```
```
--json
```
flag preferred for all read operations (deterministic parsing)

Install

brew install steipete/tap/imsg

Credit

CLI by steipete. Adopted per ADR-0067.