imsg

Q: How do I install imsg?

Run npx skills add https://github.com/joelhooks/joelclaw --skill imsg in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/imsg/ (personal) or .claude/skills/imsg/ (project).

by joelhooks

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.

Installs: 41
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/joelhooks/joelclaw --skill imsg

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads imsg automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.

Flagg: imsg via Executor

On Flagg, do not call imsg from a terminal for reads. Use Executor's saved connection, which runs a signed service that holds the Full Disk Access grant.

Address: tools.imsg.org.flaggImsg.<tool>. Discover with tools.search({ namespace: "imsg", query: "" }).
Tools: imsg_status, imsg_chats, imsg_group, imsg_history, imsg_send. Call imsg_status first.
Service: LaunchAgent com.joel.imsg-mcp on 127.0.0.1:4793, code in packages/imsg-mcp, bundle /Applications/imsg-mcp.app.
imsg_send needs Joel's explicit approval for recipient and text. An org require_approval policy on it is expected in Executor; check the Tools tab. Attachments only from ~/.joelclaw/imsg-outbox or /tmp. A killed send returns "outcome unknown", so check Messages.app before retrying.
Health: curl -s http://127.0.0.1:4793/healthz and launchctl print gui/501/com.joel.imsg-mcp. Restart with launchctl kickstart -k gui/501/com.joel.imsg-mcp.
Bearer: imsg_mcp_bearer_token in agent-secrets. Never print it.
Joel-only grants: Full Disk Access for /Applications/imsg-mcp.app (re-toggle after any re-sign) and the Automation prompt for Messages.app on first send.

Full receipts: ~/Code/joelhooks/dark-wizard/.brain/projects/imsg-mcp-executor-2026-09.svx.

FAQ

What does the imsg skill do?

How do I install imsg?

Run npx skills add https://github.com/joelhooks/joelclaw --skill imsg in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/imsg/ (personal) or .claude/skills/imsg/ (project).

Which AI agents can use imsg?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is imsg safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains imsg?

It is published by joelhooks in joelhooks/joelclaw. It has 41 recorded installs.

More from joelhooks/joelclaw

View all →

contacts

joelhooks/joelclaw

Add, enrich, and manage contacts in Joel's Vault. Fire the Inngest enrichment pipeline for full multi-source dossiers, or create quick contacts manually. Use when: 'add a contact', 'enrich this person', 'who is X', 'VIP contact', 'update contact', or any task involving the Vault/Contacts directory.

Productivity & Automation3.3K installs