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
npx skills add dvdsgl/claude-imessage --skill imessage -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/imessage/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/imessage/
1Skills CLI (Vercel)
npx skills add dvdsgl/claude-imessage --skill imessage -a codex2Manually: put the files in place
.agents/skills/imessage/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add dvdsgl/claude-imessage --skill imessage -a cursor2Manually: put the files in place
.cursor/skills/imessage/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install dvdsgl/claude-imessage skills/imessage2Manually: put the files in place
.github/skills/imessage/SKILL.md1Skills CLI (Vercel)
npx skills add dvdsgl/claude-imessage --skill imessage -a gemini-cli2Platform CLI
gemini skills install https://github.com/dvdsgl/claude-imessage --path skills/imessageManually: put the files in place
.devin/skills/imessage/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add dvdsgl/claude-imessage --skill imessage -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.