Agent skill

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.

View SKILL.md on GitHub Repository
Stars 51
Forks 3

Install this agent skill to your Project

npx add-skill https://github.com/joelhooks/joelclaw/tree/main/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

bash
imsg chats --limit 10 --json

Read history

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

Watch for new messages

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

Send

bash
# By email (iMessage)
imsg send --to "[email protected]" --text "hello"

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

# With file attachment
imsg send --to "[email protected]" --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:

bash
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

bash
brew install steipete/tap/imsg

Credit

CLI by steipete. Adopted per ADR-0067.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

joelhooks/joelclaw

skill-review

Audit and maintain the joelclaw skill inventory. Use when checking skill health, fixing broken symlinks, finding stale skills, or running the skill garden. Triggers: 'skill audit', 'check skills', 'stale skills', 'skill health', 'skill garden', 'broken skill', 'skill review', 'fix skills', 'garden skills', or any task involving skill inventory maintenance.

51 3
Explore
joelhooks/joelclaw

cli-design

Design and build agent-first CLIs with HATEOAS JSON responses, context-protecting output, and self-documenting command trees. Use when creating new CLI tools, adding commands to existing CLIs (joelclaw, slog), or reviewing CLI design for agent-friendliness. Triggers on 'build a CLI', 'add a command', 'CLI design', 'agent-friendly output', or any task involving command-line tool creation.

51 3
Explore
joelhooks/joelclaw

daily-summary

Generate a daily system activity summary across all joelclaw subsystems. Triggers on 'daily summary', 'what happened today', 'system report', 'today's tally', 'activity summary', 'what did we do', 'daily report'.

51 3
Explore
joelhooks/joelclaw

inngest-durable-functions

Create and configure Inngest durable functions. Covers triggers (events, cron, invoke), step execution and memoization, idempotency, cancellation, error handling, retries, logging, and observability.

51 3
Explore
joelhooks/joelclaw

recall

Fan-out search across all memory sources when context is unclear or vaguely referenced. Triggers on: 'from earlier', 'remember when', 'what we discussed', 'that thing with', 'the conversation about', 'did we ever', 'what happened with', 'you mentioned', 'we talked about', 'earlier today', 'last session', 'the other day', or any vague reference to past context that needs resolution before the agent can act.

51 3
Explore
joelhooks/joelclaw

inngest-local

Set up self-hosted Inngest on macOS as a durable background task manager for AI agents. Interactive Q&A to match intent — from Docker one-liner to full k8s deployment with persistent state. Use when: 'set up inngest', 'background tasks', 'durable workflows', 'self-host inngest', 'event-driven functions', 'cron jobs', or any request for a local workflow engine.

51 3
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results