Agent skill

imessage

Send and read iMessages/SMS from macOS. Use for texting contacts, scheduling services, or automating message-based workflows. Triggers on queries about texting, messaging, SMS, iMessage, or contacting someone via text.

View SKILL.md on GitHub Repository
Stars 77
Forks 14

Install this agent skill to your Project

npx add-skill https://github.com/letta-ai/skills/tree/main/tools/imessage

SKILL.md

iMessage Integration

Send and read iMessages/SMS using the imsg CLI tool on macOS.

Setup

1. Build the imsg CLI

Clone and build the tool:

bash
git clone https://github.com/letta-ai/imsg.git ~/repos/imsg
cd ~/repos/imsg
swift build -c release

The binary will be at ~/repos/imsg/.build/release/imsg (or use the pre-built binary if available at ~/repos/imsg/bin/imsg).

2. Grant Permissions

Required macOS permissions (System Settings → Privacy & Security):

Permission Location Required For
Full Disk Access Privacy & Security → Full Disk Access Reading message history
Automation Privacy & Security → Automation Sending messages via Messages.app

3. Enable SMS Relay (Optional)

To send SMS (green bubbles) to non-iMessage users:

  1. On iPhone: Settings → Messages → Text Message Forwarding
  2. Enable forwarding to your Mac

Commands

List Recent Chats

bash
imsg chats --limit 10
imsg chats --limit 10 --json

Output format: [chat_id] (identifier) last=timestamp

View Chat History

bash
# View last 20 messages in a chat
imsg history --chat-id <id> --limit 20

# With attachments metadata
imsg history --chat-id <id> --limit 20 --attachments

# Filter by date
imsg history --chat-id <id> --start 2026-01-01T00:00:00Z --json

Send a Message

bash
# Send to phone number
imsg send --to "+15555555555" --text "Hello!"

# Send with attachment
imsg send --to "+15555555555" --text "Here's the file" --file /path/to/file.jpg

# Force iMessage or SMS
imsg send --to "+15555555555" --text "Hi" --service imessage
imsg send --to "+15555555555" --text "Hi" --service sms

# Send to existing chat by ID
imsg send --chat-id 86 --text "Hello!"

Watch for New Messages

bash
imsg watch --chat-id <id> --debounce 250ms

Best Practices

Phone Number Format

  • Use E.164 format: +1XXXXXXXXXX for US numbers
  • Include country code for international

SMS vs iMessage

  • iMessage (blue bubble): Default for Apple device users, free
  • SMS (green bubble): Requires iPhone relay, may have carrier charges
  • Use --service sms when recipient doesn't have iMessage

Message Etiquette for Agents

  • Be concise - Keep messages short and clear
  • Be human - Write naturally, not robotically
  • Identify context - If following up, reference previous conversation
  • Respect timing - Avoid early morning/late night messages

Common Use Cases

Scheduling Services

bash
imsg send --to "+14155551234" --text "Hi! Do you have availability this Saturday for a cleaning?"

Following Up

bash
imsg send --to "+14155551234" --text "Just wanted to follow up on my earlier message. Let me know when you have a chance!"

Confirming Appointments

bash
imsg send --to "+14155551234" --text "Confirming our appointment for Saturday at 10am. See you then!"

Troubleshooting

Issue Solution
"not authorized" error Grant Automation permission to terminal
Can't read messages Grant Full Disk Access to terminal
SMS not sending Enable Text Message Forwarding on iPhone
Message stuck sending Check Messages.app is signed in and working

Technical Notes

  • Uses AppleScript for sending (no private APIs)
  • Read operations are read-only on the Messages SQLite database
  • Requires macOS 14+ with Messages.app configured
  • Binary location: ~/repos/imsg/bin/imsg (adjust path as needed)

Recommended Agent Skills

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

letta-ai/skills

yelp-search

Search Yelp for local businesses, get contact info, ratings, and hours. Use when finding services (cleaners, groomers, restaurants, etc.), looking up business phone numbers to text, or checking ratings before booking. Triggers on queries about finding businesses, restaurants, services, or "look up on Yelp".

77 14
Explore
letta-ai/skills

extracting-pdf-text

Extract text from PDFs for LLM consumption. Use when processing PDFs for RAG, document analysis, or text extraction. Supports API services (Mistral OCR) and local tools (PyMuPDF, pdfplumber). Handles text-based PDFs, tables, and scanned documents with OCR.

77 14
Explore
letta-ai/skills

morph-warpgrep

Integration guide for Morph's WarpGrep (fast agentic code search) and Fast Apply (10,500 tok/s code editing). Use when building coding agents that need fast, accurate code search or need to apply AI-generated edits to code efficiently. Particularly useful for large codebases, deep logic queries, bug tracing, and code path analysis.

77 14
Explore
letta-ai/skills

obsidian-cli

Work with Obsidian vaults using the official Obsidian CLI. Read, create, append, search, and manage notes, daily notes, properties, tags, tasks, sync, and more from the terminal. Use when the user mentions Obsidian, notes, vault, daily notes, or when working with markdown knowledge bases. Requires Obsidian desktop app running with CLI enabled in Settings > General.

77 14
Explore
letta-ai/skills

mcp-builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

77 14
Explore
letta-ai/skills

google-workspace

Connect to Gmail and Google Calendar via OAuth 2.0. Use when users want to search/read emails, create drafts, search calendar events, check availability, or schedule meetings. Triggers on queries about email, inbox, calendar, schedule, or meetings.

77 14
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results