GuidesPut your agent to workApple ecosystem

Connect to the Apple ecosystem

Your agent lives on your Mac. With a few small skills, it can also reach the apps you already use every day: it can triage your mail, manage your calendar, keep your reminders straight, look people up in Contacts, and text someone when you ask. You describe what you want in plain language, and it does the fiddly clicking for you.

Everything here runs locally. There is no cloud middleman and no account to sign up for. The skills talk to Mail, Calendar, Contacts, Reminders, and Messages directly on your machine, so your email, your schedule, and your conversations stay on your Mac.

Local and private

These skills use the same automation your Mac already offers to any app. Nothing is uploaded, and no third-party server sees your data. Your Mac will ask your permission the first time each skill needs access, and you stay in control of what you approve.

The fast way: let your agent do it

You don't have to run any of these commands yourself. Copy the prompt below and paste it into your agent, in a conversation opened on your Mac. It reads this guide, installs the skills you want, and walks you through each Mac permission prompt as it comes up. You approve; it does the clicking.

Follow this guide to set me up with access to the Apple apps on my Mac — Calendar, Reminders, Contacts, Mail, and Messages: https://divergentsystems.ai/guides/apple-ecosystem

First, run a preflight check: which node npx brew, and tell me which of those are missing before doing anything else — I need Node.js for every step here, and Homebrew for two of them. If Node is missing, stop and tell me how to install it.

Then detect whether I'm on Claude Code or Codex and handle the setup for me. Install the skills one at a time, and after each one run a read-only test to confirm it works before moving to the next. Heads up: on Claude Code, the very first install command may need me to approve it by hand, because it names a package that came from this web page rather than from me typing it — that's expected, just tell me when it happens. When macOS asks for a permission, tell me exactly what's about to pop up and wait for me to approve it.

Prefer to understand it first? Read on — the rest of the guide walks through each app and permission by hand, so you know exactly what your agent is doing.

Before you start

You need four things:

A Mac. These skills are macOS-only. They use Apple's built-in apps, so they will not work on Windows or Linux.
An agent that's already set up. If you haven't done that yet, start with the installation guide and come back here.
Node.js — required for every step. All five skills install with a command called npx, which comes with Node.js. If you don't have Node, nothing on this page will run, including Calendar, the recommended first step. Check by pasting which node npx into your agent: if it prints two paths, you're set; if it prints nothing, you need Node first. Homebrew makes it a one-liner (brew install node), or download the installer from nodejs.org.
Homebrew, for two of the skills (Reminders and Messages) and the easiest way to get Node above. It's a free tool for installing Mac software. If you don't have it, paste the one-line installer from brew.sh into your agent and ask it to set Homebrew up. Calendar, Contacts, and Mail don't strictly need Homebrew, but they all need Node.

Every skill installs with one command in the same shape — npx skills add <source> --agent claude-code. The source differs by skill (each is maintained in a different place), so use the exact command shown in each app's section below rather than a single template. You can browse any of them at skills.sh.

npx skills add <source-shown-below> --agent claude-code

The --agent claude-code part keeps the install tidy — it adds the skill to your agent only, instead of scattering copies into every other AI editor it can find. On Codex use --agent codex; on OpenClaw use --agent openclaw. (The commands in each section omit the flag for brevity — add it to target one agent, or the installer will ask.)

A note on sources, since they vary: Calendar, Contacts, and Mail install from repos we maintain (dwbutler/…) because the original community versions were left unmaintained; Reminders and Messages install from their upstream OpenClaw homes (openclaw/…). All are the same skills you'd find in the wild, just pointed at sources that actually get looked after.

You don't have to type these yourself. Send this page to your agent and it can run the commands for the apps you want. You approve the Mac permission prompts when they pop up.

One thing to expect on Claude Code: the first install command may pause and ask you to approve it before it runs. That's a safety feature, not a bug — Claude Code won't auto-run a command that installs a package it read off a web page (this one) rather than one you typed yourself. Just confirm it when asked, and the rest follow normally. Codex handles this differently and usually won't stop you here.

One small thing your agent handles automatically: two of these skills (Calendar and Mail) ship helper scripts that need to be made runnable once, with chmod +x. If a script ever fails with "Permission denied," that's all it is — your agent will fix it and re-run.

The apps below are in a deliberate order: Calendar and Reminders first (safe, they mostly organize your own stuff), then Contacts (read-only lookups), and Mail and Messages last, because those two can send things as you. Do them in order, or pick only the ones you want. Each app has a short description, the install command, the permission prompt to expect, a quick read-only test, and one example you can say to your agent.

Do one app at a time. Install a skill, run its read-only test, and confirm it actually works before moving to the next one. That way, if something needs a permission or a small fix, you catch it on that one app instead of untangling five at once. The read-only test never changes or sends anything — it just proves your agent can see the data.

Calendar

Your agent can read what's on your calendar, search for events, and create, edit, move, or delete them — across every calendar you have. Great for "what does my week look like?" and "put that on my calendar."

Install

npx skills add dwbutler/apple-calendar

Permission to expect: the first time your agent touches your calendar, macOS shows a small pop-up asking to give access to Calendar. Click OK (or Allow). That's it.

Confirm it works (read-only): before you move on, say "list all my calendars." If your agent names them back, this skill is working. Nothing is changed or created — it's just reading.

Try saying:

"What's on my calendar this week? And add a dentist appointment next Tuesday at 3pm."

Reminders

Your agent can list your reminders, add new ones, edit them, and mark them done or delete them. Good for offloading the "don't forget to…" thoughts as they come up.

Install (two commands)

This skill uses a small helper tool called remindctl. Install the tool with Homebrew first, then add the skill:

brew install steipete/tap/remindctl
npx skills add openclaw/openclaw@apple-reminders

Permission to expect: the first time it runs, macOS asks to give access to Reminders. Click OK. If it doesn't appear to be working, it usually means that prompt is waiting for you — check for it.

If the permission dialog never appears, do this one step yourself. Reminders is the one skill whose first-time approval can't always be triggered from inside your agent — macOS only shows that pop-up for a program running directly in a real terminal window, and your agent's commands run in a sandbox that doesn't count. If your agent says it's stuck on Reminders permission, open the Terminal app yourself and run this one line:

remindctl authorize

The Reminders pop-up appears; click OK. That's a one-time thing — after you approve it once, your agent can read and manage Reminders normally from then on. You can check it took with remindctl status.

Confirm it works (read-only): before you move on, say "show me what's on my reminders lists." If your agent reads them back, this skill is working. It's only looking, not adding anything.

Try saying:

"Add 'call the pharmacy' to my reminders for tomorrow morning, and show me what's still open on my list."

Contacts

Your agent can look people up in your address book and turn a phone number into a name (or the other way around). This one is read-only — it looks things up, it doesn't change your contacts. It's also what makes Mail and Messages feel natural, because your agent can figure out who "Mom" or "Sam from work" is.

Install

npx skills add dwbutler/apple-contacts

Permission to expect: macOS asks to give access to Contacts the first time. Click OK.

Confirm it works (read-only): before you move on, say "how many contacts do I have?" or look up someone you know by name. If your agent answers, this skill is working. Contacts is read-only, so nothing changes either way.

Try saying:

"Whose number is this?" (paste a number) — or — "What's Sam's email address?"

Mail

Your agent can read your inbox, search it, open individual messages, mark them read or unread, delete them — and send and reply to email as you. This is the first send-capable skill, so it needs a little more permission (the permissions step below covers it once for both Mail and Messages).

Install

npx skills add dwbutler/apple-mail

Reading your inbox uses a tool called sqlite3, which already ships with macOS — nothing extra to install.

Heads up: this one installs from dwbutler/apple-mail, a version we maintain. It matters most here — the widely-circulated community copy had a bug where an agent-composed reply could go out with an empty body and no error, and this version fixes it (verified end-to-end). It still installs under the name apple-mail, same as everything else.

Permission to expect: the first time your agent sends through Mail, macOS asks for Automation permission ("…wants to control Mail") — click OK. Reading the inbox usually works from the access your agent app already has; if inbox reading fails, granting Full Disk Access to your agent app (Claude Code or Codex) fixes it. The permissions step below covers both.

Confirm it works (read-only): before you move on, say "search my mail for a word you know is in there, like 'invoice', and show me a few results." If your agent lists real messages, reading works. This is the reading side only — don't have it send anything yet.

Try saying:

"Summarize my unread email and tell me which ones actually need a reply." (Reading only — always start here before you let it send.)

Messages (iMessage & SMS)

Your agent can list your chats, read history, watch a conversation live, and send iMessages or texts as you, including attachments. The skill is called imsg. It wraps a small tool of the same name (homepage imsg.to).

Install (two commands)

Install the imsg tool with Homebrew first, then add the skill:

brew install steipete/tap/imsg
npx skills add openclaw/imsg@imsg

Permission to expect: like Mail, sending asks for Automation permission ("…wants to control Messages") — click OK. Reading your chat history usually works from the access your agent app already has; if it can't read history, granting Full Disk Access to your agent app (Claude Code or Codex) fixes it. The permissions step below covers both.

Confirm it works (read-only): say "list my most recent message conversations." If your agent shows your recent chats, reading works. This is the reading side only — don't have it send a text yet.

Try saying:

"Text Mom that I'll be there by six — but read it back to me before you send it."

The permissions step (Mail & Messages)

Calendar, Reminders, and Contacts each just show a small "allow access?" pop-up the first time — you click OK and you're done. Mail and Messages have one extra permission you'll definitely hit (Automation), and one you might not need at all (Full Disk Access). Here's each one and where it lives.

1. Automation — so it can send through Mail and Messages

To send an email or a text, your agent asks Mail.app or Messages.app to do it. macOS calls this "Automation." You don't have to hunt for this one — the first time your agent tries to send, macOS pops up a box like "Claude Code wants to control Mail" (or "Codex wants to control Mail"). Click OK. Do the same when it later asks about Messages.

You can review or change these anytime under System Settings › Privacy & Security › Automation. Open it directly with:

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"

2. Full Disk Access — only if reading Mail or Messages fails

Your Mail and Messages history live in files that macOS keeps locked down. In practice, most agent apps can already read them from the access they were granted at install, so try reading first — you may not need this step at all. If your agent says it can't read your inbox or chat history, that's the signal to turn this on.

If you do need it, the part that trips people up is which app you grant it to. It has to be the app your agent actually runs inside — for the Claude desktop app, the entry in the list is named Claude. Ask your agent to open the right settings screen for you (or paste this into it):

open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

That opens System Settings › Privacy & Security › Full Disk Access. Turn on the switch next to Claude (or Codex, whichever you use). If it isn't in the list yet, click the + button and add it from your Applications folder. Then fully quit that app and reopen it — the change doesn't take effect until you do.

Don't grant it to Terminal. If you happen to have Terminal (or iTerm) open, it's tempting to flip that switch instead — but your agent's tools don't run as Terminal, so granting Terminal does nothing and reading will still fail. Grant it to Claude (or Codex), the app the agent lives in, and restart that app. This one is easy to get wrong and hard to spot, because nothing errors — reading just keeps coming back empty.

Quick way to think about it: Automation = your agent can send (you'll always grant this). Full Disk Access = a fallback for reading, only if your inbox or chats won't load. Reminders, Contacts, and Calendar don't need either; they just ask once with their own small pop-up.

Mail and Messages can send as you. Keep yourself in the loop

The Mail and Messages skills don't just read — they can send email and texts from your accounts, as you. That's exactly what makes them useful, and it's the part to be deliberate about. A message goes out under your name; the person receiving it sees it came from you.

The fix is simple: have your agent draft first and wait for your OK before anything goes out. The skills themselves are built to confirm the recipient and content with you first — and the next step turns that into a standing rule so you never have to rely on remembering.

A gentle on-ramp: use the reading side first. Let your agent summarize your inbox and your chats for a while before you turn it loose on sending. When you do start sending, begin with low-stakes messages to people who'll understand if the wording is a little off.

Make "draft first, send on approval" a standing rule

Rather than remembering to ask every time, write the habit down once so your agent always follows it. Your agent keeps its standing instructions in a file called AGENTS.md at the top of its workspace. Ask your agent to add this rule to that file:

When sending email or messages, draft the message first and show me the recipient and the full text. Do not send until I reply with approval. This applies to new emails, replies, messages, and texts.

You can say: "Add a rule to my AGENTS.md that you always draft emails and messages first and never send until I approve." Once it's in AGENTS.md, every future session follows it without you having to bring it up again.

At a glance: what each skill can do

One row per app. "Writes / sends" is the column to notice — that's where your agent can change things or reach other people.

App	Skill	Reads	Writes / sends	Mechanism	Permission needed
Calendar	`apple-calendar`	Events across all your calendars	Create, edit, move, delete events	AppleScript	Calendar (prompts on first use)
Reminders	`apple-reminders`	Lists and reminders	Add, edit, complete, delete	remindctl CLI	Reminders (may need remindctl authorize run in Terminal once)
Contacts	`apple-contacts`	Names, numbers, details	Read-only lookups	AppleScript	Contacts (prompts on first use)
Mail	`apple-mail`	Inbox, search, message bodies	Send, reply, mark read/unread, delete	AppleScript + SQLite read	Automation (Full Disk Access only if reading fails)
Messages	`imsg`	Chats and history, live-watch	Send iMessage / SMS with attachments	imsg CLI	Automation (Full Disk Access only if reading fails)

All five run entirely on your Mac. No cloud service sits in the middle, and your data doesn't leave the machine.

Stuck? Get help Back to all guides

Stuck or need help?

Send a message and it comes straight to me. Tell me where you got stuck and I'll write back.

Rather have it done for you?

If following the steps yourself isn't how your brain works today, that's fine. On a Zoom call you share your screen and hand me control, and I set it up for you, right there on your own computer. You watch it come together and end the call with a working setup, nothing left on your plate.

Pick a time below. No pitch, no pressure, no homework beforehand.