Guide · Agent skill
How to use the imsg agent skill for iMessage and SMS
Updated · written with AI from the project's own documentation and checked against our catalogue data
The imsg skill teaches an AI agent to use the imsg command-line tool to work with the Messages app on a Mac. It is meant for people who want their assistant to list recent chats, read conversation history, or send texts and attachments on their behalf. By the end of this guide you will know what the skill does, how to install it, how to ask for things in plain language, and what to check for safety.
iMessage and SMS via imsgspinabot/brigade · MIT Download the skill Quick start
- 1Check your Mac. Confirm you are on macOS with Messages.app signed in.
- 2Install imsg. Install the imsg tool with Homebrew using the formula steipete/tap/imsg.
- 3Grant permissions. Give your terminal Full Disk Access and allow Automation for Messages.app so sending works.
- 4Download the skill. Download the imsg skill ZIP from this page and unzip it.
- 5Place the skill folder. Move the imsg folder into ~/.claude/skills/, or into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 6Make a natural request. Ask the agent to list chats, read a conversation, or send a text, naming the contact and wording.
- 7Confirm before sending. Review the recipient and message the agent proposes, then approve or correct it.
What is an agent skill and what does imsg let the agent do?
An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to use a particular tool. This skill is built around the imsg command-line tool, which reads and sends iMessage and SMS through macOS Messages.app.
Once the skill is installed and the imsg tool is available, the agent can list recent Messages.app chats, read conversation history (optionally including attachment information), watch for new messages, and send texts or files to phone numbers or Apple IDs.
- List recent chats
- Read conversation history by chat ID
- Watch a chat for new messages
- Send text, with an optional file attachment, to a phone number or Apple ID
What do you need before installing the imsg skill?
The skill only works on macOS. The source lists these requirements: macOS with Messages.app signed in, the imsg command-line tool, Full Disk Access granted to your terminal, and Automation permission for Messages.app (needed for sending).
The imsg tool is installed through Homebrew using the formula steipete/tap/imsg. The skill's metadata lists this as its install method.
- A Mac running macOS, with Messages.app signed in
- The imsg tool, installed via Homebrew formula steipete/tap/imsg
- Full Disk Access granted to your terminal app
- Automation permission for Messages.app, for sending messages
brew install steipete/tap/imsgHow do you install the imsg skill?
Download the imsg skill ZIP from this page and unzip it. To make it available across your projects, place the imsg folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the imsg skill with natural requests?
You do not need a special command. Ask the agent in plain language, and it will decide whether the skill applies. The skill is meant for requests that explicitly involve iMessage or SMS, such as sending a text, reading a conversation, or checking recent chats.
The skill also tells the agent when not to use it. For example, replies inside the current conversation are handled normally, and messages on WhatsApp, Telegram, Slack or Discord are routed to other tools.
- "Show my five most recent Messages chats."
- "Read the last 20 messages in my chat with Sam."
- "Text mom that I'll be late."
- "Send this photo to +14155551212 with the message 'Check this out'."
What commands does the imsg skill use?
The skill's SKILL.md shows the agent how to call imsg. Listing chats, viewing history, watching for messages, and sending are shown below exactly as they appear in the source. You do not need to type these yourself, but they help you understand what the agent is doing.
- Sending supports --service imessage, --service sms, or --service auto (the default, where Messages.app decides).
imsg chats --limit 10 --json
imsg history --chat-id 1 --limit 20 --attachments --json
imsg watch --chat-id 1 --attachments
imsg send --to "+14155551212" --text "Hello!" --service imessageWhat safety rules does the skill enforce?
The skill tells the agent to always confirm the recipient and message content before sending, never to send to unknown numbers without explicit approval, check that an attachment path exists before sending, and avoid spamming. Bulk or mass messaging must be confirmed with you first, and group chat membership management is not supported.
The skill runs scripts (the imsg tool is a local command) and the source states it does not use the network. Review the commands the agent proposes before approving them, especially anything that sends a message.
- Confirm recipient and wording before every send
- Do not message unknown numbers without your approval
- Check attachment file paths before sending
- Mass texting requires your confirmation
What tips help the imsg skill work well?
Ask the agent to check recent chats first. The skill's example workflow lists chats, finds the right contact, asks you to confirm, and only then sends. Stating the contact name and exact wording in your request makes this faster.
If the skill does not seem to run, check that you are on a Mac, that imsg is installed, and that Full Disk Access and Automation permissions are granted.
- Name the contact and the exact text you want sent
- Ask for recent chats before drafting a reply
- Use --service sms if you need to force a green-bubble SMS
What people use it for
- Asking the agent for your five most recent Messages chats before replying
- Reading the last 20 messages in a conversation to catch up
- Sending a short text such as a running-late note after confirming the contact
- Sending a photo or file to a phone number or Apple ID with a short message
- Watching a single chat for new messages while you work
Frequently asked questions
Is the imsg skill free to use?
The skill is published under the MIT licence, as stated in its listing. The imsg tool itself is installed through Homebrew; check its own project for any terms that apply to it.
What are the requirements for the imsg skill?
You need a Mac running macOS with Messages.app signed in, the imsg command-line tool installed via Homebrew formula steipete/tap/imsg, Full Disk Access for your terminal, and Automation permission for Messages.app to send messages.
Does the imsg skill work on Windows or Linux?
No. The skill is limited to macOS (darwin) and needs Messages.app, so it will not work on Windows or Linux.
Can the imsg skill send WhatsApp or Telegram messages?
No. The skill tells the agent to route WhatsApp, Telegram, Signal, Discord and Slack messages to other tools or channels instead.
How do I install the imsg skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills.
Why won't the imsg skill read or send my messages?
Check that you are on macOS, that imsg is installed, that Messages.app is signed in, and that your terminal has Full Disk Access. Sending also needs Automation permission for Messages.app.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use the imsg skill if you are on a Mac, already use Messages.app, and want an agent to read chats or send iMessages and texts while you approve each send. Pick something else if you use Windows or Linux, need WhatsApp or Telegram, or want to run bulk messaging.
Download the skill