Skip to main content
skill CX Codex

imessage · dvdsgl — Claude Code skill: what it does, how to install

imessage — a macOS skill that lets an agent read Messages conversations and send texts or files straight from the chat database and AppleScript.

MIT 1 installs ★ 54 updated 2025-12-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dvdsgl/claude-imessage --skill imessage -a claude-code
Open on GitHub

What imessage does

The skill ships bash scripts under .claude/skills/imessage/ for reading conversations, checking for new texts, and sending messages or files through the Messages app. Reading relies on direct access to ~/Library/Messages/chat.db via read-messages-db.sh and check-new-messages-db.sh, avoiding the permission issues that plain AppleScript reads can hit. Outgoing messages and files go through AppleScript scripts: send-message.sh, send-to-chat.sh, send-file.sh.

A separate get-message-attachments.sh script pulls files from received messages, converting HEIC photos to JPEG and resizing large images down to 1024px before saving them to ~/tmp/. list-conversations.sh gives a quick overview of recent threads. The setup only runs on macOS with Messages signed into iMessage or SMS, and some actions need Full Disk Access granted in system settings.

What it helps with

  • pull up message history with one contact
  • send a text by contact name or phone number
  • poll for new incoming messages to drive an auto-reply bot
  • send a photo or document over iMessage
  • extract and convert attachments from received texts

Example prompts for the agent

  • Show me the last 10 messages from John Doe
  • Check for new messages from +1234567890
  • Send a message to John Doe saying hello

How to install imessage

1Skills CLI (Vercel)

npx skills add dvdsgl/claude-imessage --skill imessage -a claude-code

2Manually: put the files in place

~/.claude/skills/imessage/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/imessage/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about imessage

How do I install imessage in Claude Code?

Run npx skills add dvdsgl/claude-imessage --skill imessage -a claude-code; the skill lands in ~/.claude/skills/imessage/SKILL.md.

What does the imessage skill do?

It pulls conversation history and new texts straight from the Messages database, and sends messages or files through AppleScript.

What does imessage require to work?

It only runs on macOS with Messages signed into iMessage or SMS, and some operations need Full Disk Access enabled in system settings.

Source text

SKILL.md · MIT
---
name: imessage
description: Interact with Messages app - read conversations, send messages, and check for new messages using AppleScript and SQLite database access
---

# iMessage Management Skill

This skill provides comprehensive Messages app interaction capabilities through command-line tools.

## Available Tools

All tools are located in `.claude/skills/imessage/` and use either AppleScript or direct SQLite database access to interact with the Messages app.

### Database vs AppleScript Approach

- **Database tools** (`*-db.sh`): Read messages directly from the Messages SQLite database (`~/Library/Messages/chat.db`). More reliable and faster, supports full message history including sent messages with proper text extraction.
- **AppleScript tools** (original): Use AppleScript automation. Sending works reliably, but reading messages may have permission issues on some macOS systems.

**Recommended**: Use database tools for reading (`read-messages-db.sh`, `check-new-messages-db.sh`) and AppleScript for sending (`send-message.sh`, `send-to-chat.sh`).

### 1. Read Messages from Database (`read-messages-db.sh`) ⭐ RECOMMENDED

Read messages directly from the Messages SQLite database. This is the most reliable method for reading message history.

**Usage:**
```bash
# Read recent messages by phone number
.claude/skills/imessage/read-messages-db.sh "1234567890" --limit 10

# Read recent messages (all conversations)
.claude/skills/imessage/read-messages-db.sh --limit 20
```

**Features:**
- Reads both incoming and outgoing messages
- Extracts text from outgoing messages (stored in attributedBody)
- Fast and reliable
- Shows formatted timestamps
- No permission issues

### 2. Check New Messages from Database (`check-new-messages-db.sh`) ⭐ RECOMMENDED

Check for recent incoming messages from the database. Used by the iMessage auto-reply daemon.

**Usage:**
```bash
# Check recent messages from specific number
.claude/skills/imessage/check-new-messages-db.sh "1234567890"

# Check all recent incoming messages
.claude/skills/imessage/check-new-messages-db.sh
```

**Output Format:**
```
MSG_ID: <unique_hash>
ROWID: <message_id>
DATE: <readable_timestamp>
TEXT: <message_text>
FROM: <phone_number>
CHAT: <chat_identifier>
---
```

### 3. Send Message (`send-message.sh`) ⭐ RECOMMENDED

Send a message to a contact or phone number via AppleScript.

**Usage:**
```bash
# Send to contact name
.claude/skills/imessage/send-message.sh "John Doe" "Hey, how are you?"

# Send to phone number
.claude/skills/imessage/send-message.sh "+1234567890" "Message text here"

# Send with content from stdin
echo "Message content" | .claude/skills/imessage/send-message.sh "John Doe"
```

### 4. Send to Chat (`send-to-chat.sh`)

Send a message to a specific chat by chat identifier (useful for group chats).

**Usage:**
```bash
# Send to group chat
echo "Message text" | .claude/skills/imessage/send-to-chat.sh "chat123456789"

# Send directly
.claude/skills/imessage/send-to-chat.sh "chat123456789" "Message text"
```

### 5. Send File (`send-file.sh`)

Send images, documents, or other files via iMessage using AppleScript.

**Usage:**
```bash
# Send file to phone number
.claude/skills/imessage/send-file.sh "+1234567890" "/path/to/file.jpg"

# Send file to contact name
.claude/skills/imessage/send-file.sh "John Doe" "/Users/user/Desktop/image.png"
```

**Supported file types:**
- Images: JPG, PNG, HEIC, GIF
- Documents: PDF, DOCX, TXT
- Videos: MP4, MOV
- Any file type supported by iMessage

### 6. List Conversations (`list-conversations.sh`)

List recent conversations with contact names and message counts.

**Usage:**
```bash
# List all conversations
.claude/skills/imessage/list-conversations.sh

# List first N conversations
.claude/skills/imessage/list-conversations.sh --limit 10
```

### 7. Get Message Attachments (`get-message-attachments.sh`)

Retrieve and process attachments from received messages.

**Usage:**
```bash
# Get attachments from a specific message (use ROWID from check-new-messages-db.sh)
.claude/skills/imessage/get-message-attachments.sh <message_rowid>
```

**Output format:**
```
IMAGE|/path/to/output.jpg|image/jpeg|original.jpg|1024x768|125K
FILE|/path/to/file.pdf|application/pdf|document.pdf||2.3M
```

**Features:**
- Automatically converts HEIC images to JPEG
- Downscales large images to 1024px max dimension
- Saves processed images to `~/tmp/`
- Preserves original files for non-image attachments

## Workflow Guidelines

### When building iMessage automation:

1. **Reading Messages** (Database Approach - Recommended)
   - Use `read-messages-db.sh` with phone number to see conversation history
   - Displays both incoming and outgoing messages with proper text
   - Shows clear timestamps and message direction

2. **Sending Messages**
   - Verify the contact name or phone number format
   - Use `send-message.sh` for direct messages
   - Use `send-to-chat.sh` for group chats
   - Confirm the message was sent successfully

3. **Checking New Messages** (Database Approach - Recommended)
   - Use `check-new-messages-db.sh` to check for recent incoming messages
   - Filter by phone number for specific contacts
   - Parse output to track which messages have been processed
   - Used by the iMessage auto-reply daemon

4. **For Automated Daemons**
   - Use `check-new-messages-db.sh` to poll for new messages
   - Track processed messages using message IDs
   - Use `read-messages-db.sh` to get conversation context
   - Use `send-message.sh` or `send-to-chat.sh` to send replies

## Best Practices

- **Contact Names**: Use exact contact names as they appear in Messages
- **Phone Numbers**: Use full format with country code (e.g., +1234567890)
- **Message Privacy**: Be mindful of sensitive information in messages
- **User Confirmation**: Always confirm before sending messages
- **Error Handling**: Check for errors and inform the user
- **Quoting**: Always properly quote contact names and message content in bash commands

## Important Notes

- All scripts require macOS with the Messages app
- Messages app must be signed in to iMessage or SMS
- AppleScript support is built into macOS
- The Messages app does not need to be open for these tools to work
- Some operations may require Full Disk Access permission in System Preferences

## Troubleshooting

- If contacts aren't found, try using their phone number instead
- Check that Messages has proper permissions in System Preferences > Security & Privacy
- Ensure you're signed in to iMessage in the Messages app
- If sending fails, verify the recipient's contact information

© dvdsgl · MIT · dvdsgl/claude-imessage

Similar skills

All skills for Automation and no-code: n8n, Zapier, Make →

imessage by other authors comes first.

imessage Hermes Agent Lets your coding agent read Messages.app chats and send iMessage or SMS from the terminal on macOS. Handy when the conversation stays local. CX Codex +1 496installs imessage photon-hq Picks the right Photon API for an iMessage job and keeps the code on that one contract, whether it runs on your Mac or through a hosted service. CX Codex +1 236installs imessage-query terrylica imessage-query pulls conversations out of ~/Library/Messages/chat.db with SQLite, searches across chats, and recovers text from binary attributedBody blobs. CX Codex +1 159installs iMessage History anipottsbuilds The iMessage History MCP server searches and reads Apple Messages history on macOS. Use it when an agent needs conversation context without sending messages. CX Codex +1 ★ 34repo stars imessage-max cyberpapiii imessage-max — a Swift MCP server that lets an agent read, search and send iMessage on macOS, turning phone numbers into contact names. CX Codex +1 ★ 7repo stars Apple Mail mgcrea MCP server connecting macOS Apple Mail to coding agents. It searches local messages and reads email bodies directly on your Mac without external IMAP logins. CX Codex +1 ★ 6repo stars chat-adapter-imessage photon-hq The chat-adapter-imessage skill explains how to connect the Vercel AI SDK to iMessage with Photon’s adapter. Use it when building an assistant that sends and receives iMessage conversations. CX Codex +1 126installs capture-screen daymade capture-screen — a skill for programmatic screenshot capture on macOS: it finds window IDs, changes the view through AppleScript and grabs the frame with screencapture. CX Codex +1 1,100installs

Project sponsors

Companies that keep this analytics open