iMessage Status Check.
Text 'what's on my plate today' to your agent. Get a clean summary back in ten seconds. No computer needed. This is the first build where your phone, not your terminal, is the interface to your second brain. Your agent reads your calendar, your inbox, and your Cairns waypoints, then writes back a short status. macOS only, because the listener lives on top of Apple's Messages app.
- A phone-first status query you can fire from anywhere. Standing in line, between meetings, on a walk. The answer lands as a reply iMessage in seconds.
- A reusable observer pattern where iMessage is the inbox, your agent is the worker, and a reply iMessage is the output. Every later phone-first build inherits this shape.
- Proof your agent works without you in front of it that you can show a friend or partner without opening your laptop. The artifact is small. The shift is what compounds.
Wire it up with Claude.
Hand the build off to Claude in one paste. There is no single upstream blueprint for this card. Claude assembles the listener on top of the foundation skills and connectors you already have, pausing for your confirmation between steps.
How this fits in the OS.
Your cairns-query skill (the "what do I know" query layer over your second brain), your what-do-i-have skill (the status retrieval layer for your installed toolbox and current context), your Gmail and Calendar MCPs (Claude Desktop calls these connectors) from Stage 02, and macOS. The listener sits on top of Apple's Messages app and cannot run on Windows or Linux.
iMessage as the inbox, your local agent as the worker, a reply iMessage as the output. No new cloud service, no new deploy, no new dashboard. The build is local on your Mac and stays local.
The phone-first pattern. Once iMessage is a working inbox for your agent, the same observer shape applies to "log this decision," "remember this," and any other ask you want to fire from your phone instead of your computer.
What you'll build.
A small, single-purpose iMessage listener. It watches your Messages app for one trigger phrase ("what's on my plate today") from one trusted sender (you, from your phone). When it sees the phrase, it runs cairns-query against your second brain, pulls today's calendar and any unread starred mail through the Gmail and Calendar MCPs, composes a short reply, and sends it back to you as an iMessage. Ten seconds, end to end.
This is not a chatbot. It does one thing on one trigger phrase from one contact. That constraint is what makes it safe to leave running while you're away from your computer. Later builds widen the surface. This first one stays narrow on purpose.
In a Lightning Lesson the team shared the pattern of using iMessage as an agent inbox: the listener watches the Messages database on disk, filters to a known sender, and only acts on hard-bounded triggers. The same pattern works for SMS gateways and Telegram, but iMessage is the one most cohort members already have on their phone and their computer, which is why it's the first stop.
What changes for you.
The artifact is small. The shift in how you reach your second brain is large. Three changes, in order of how soon you'll feel them:
- Your phone becomes the front door. The first time you fire a query from a grocery line and get a clean status back before you've moved up to the register, something rearranges. The computer stops being the only place your agent lives.
- You stop drafting status updates in your head. The "what am I doing today" loop that used to happen in your head on the way to the shower happens once, in a text thread, with the agent doing the assembly work.
- You start trusting the agent works while you're away from your desk. Not as a metaphor. The reply lands whether you're at your computer or not. Every later phone-first build assumes you have felt this once.
Before you start.
Four things specific to this build
- macOS. The listener reads Apple's Messages database. This card does not work on Windows or Linux. If you are on Windows, skip this card and come back when you have a Mac in the loop.
- iMessage signed in on the same Mac you run Claude Code on. Open Messages, confirm you can send and receive a test message to your own phone.
- Cairns is set up. You've worked through The Cairns Three Tiers and your vault has at least L1 waypoints. The reply pulls from L1, so if L1 is empty, the reply will be thin.
- Gmail and Calendar MCPs wired. If you have not run Stage 02 yet, run that first. Check with
/mcpin Claude Code. Both should show green. If either is red, the reply will be missing half its inputs.
Zero. Everything runs locally on your Mac. The listener is a small script. No new subscription, no new deploy.
The build.
Eight steps, about an hour. No upstream blueprint ships this exact build, so each step names the foundation piece you're assembling on top of. The starter prompt at the top of this card hands the whole sequence to Claude in one paste; if you'd rather walk it manually, here's the same sequence laid out.
Confirm you're on macOS and Messages is alive
2 minOpen Messages on your Mac. Send a one-word message to your own phone. Confirm it lands. If Messages is not signed in, sign in with the same Apple ID as your iPhone. The listener watches the Messages database, so the app has to be alive and synced.
Confirm your connectors are alive
2 minThe reply pulls today's calendar and your important mail through the Gmail and Calendar MCPs you wired in Stage 02. A five-second check now beats a confusing failure later.
/mcp
Gmail and Calendar should both show green. If either is red, jump back to Stage 02 and re-run the connector flow before continuing.
Confirm your foundation skills are installed
3 minThis build assembles two skills you already have. Confirm both files exist locally:
.claude/skills/cairns-query/SKILL.md, the "what do I know" query layer that reads your L1 waypoints first, then L2, then L3 only when needed..claude/skills/what-do-i-have/SKILL.md, the status retrieval layer that summarizes your installed toolbox and picks three useful next moves.
If either file is missing, your repo clone is stale. Pull the latest from upstream, then re-run your personalize pass.
Open .claude/skills/cairns-query/SKILL.md and .claude/skills/what-do-i-have/SKILL.md in the local workshop repo. Read both end to end and tell me back, in one sentence each, what each skill does and what inputs it expects. I want to confirm the foundation is in place before we wire the iMessage listener on top.
The agent does this for you. You're not parsing the skill specs by hand. Claude reads both files, summarizes the contract, and confirms both are installed before you build on top of them.
Grant macOS the permissions the listener needs
8 minThe listener reads the Messages database on disk and uses Apple's Automation API to send the reply. macOS gates both behind explicit permissions you have to grant by hand in System Settings. The agent cannot grant these for you. You click, with your Mac password.
- Full Disk Access for the terminal or app running Claude Code. System Settings, Privacy & Security, Full Disk Access. Add Terminal (or iTerm, or whatever shell host you use). Without this, the listener cannot read the Messages database.
- Automation permission for the terminal to control Messages. The first time the listener tries to send, macOS prompts you. Allow it. If you missed the prompt, find it in System Settings, Privacy & Security, Automation.
If the agent offers to bypass either permission, say no. Those clicks happen in System Settings, by you. macOS is doing its job. Let it.
Pick the one trusted contact and the one trigger phrase
5 minThis build is narrow on purpose. One sender, one phrase. The sender is the iCloud address or phone number you text from on your own phone. The phrase is the trigger the listener filters on.
- Trusted contact. Open Messages, open the thread to yourself, copy the address that shows up in the To field. That string is the only sender the listener will react to. Anyone else who texts the same Mac is ignored.
- Trigger phrase. The default is
what's on my plate today. Keep it natural, in plain English first, technical only if you want to type fast on a small keyboard. Tip from the team: pick something you would not say by accident in another iMessage thread.
Both values get pinned into the listener config in the next step. They are not credentials; storing them in plain text in the repo is fine.
Wire the listener on top of the foundation skills
20 minThis is the assembly step. There is no single upstream blueprint that ships this exact listener. Claude composes it from the pieces you already have: the Messages database as the input, cairns-query plus a Gmail and Calendar pull as the worker, and an AppleScript or osascript call to Messages as the output.
Wire the iMessage Status Check listener in this repo. The shape is: poll the macOS Messages database every few seconds for new inbound messages, filter to my trusted contact, match against my trigger phrase. On a match, run cairns-query against my second brain for today's plate, query Gmail for unread starred mail and Calendar for today's events through the MCPs, compose a short status reply (3 to 5 lines), and send it back to me via Messages using osascript. Show me the listener script before you start it. Do not start it yet. I want to read the trigger logic and the send logic before anything goes live.
The agent does this for you. Claude composes the script, names the inputs ("here's where the Messages database lives, here's how I'm filtering to your sender, here's how I'm calling cairns-query"), and waits for your go before starting the listener. You're approving the wiring, not writing it.
Dry test, then live test
10 minTwo passes. The dry pass proves the reply text is shaped right. The live pass proves the round trip works.
- Dry pass. From your phone, text your trigger phrase to your Mac. The listener fires. Before the reply is sent through Messages, Claude prints the composed reply text into your terminal. Read it. If the shape is wrong (too long, missing calendar, missing the L1 pull), have Claude adjust the reply template and dry-run again.
- Live pass. Once the dry text looks right, approve the send. The reply lands on your phone as a normal iMessage. Open your phone. Read the reply.
Document the kill switch
5 minOne command that stops the listener cold. You want this written down before you walk away from the build, not during a panic.
Add a one-line kill switch to the README of the listener you just wired. The command should stop the listener process immediately, no graceful shutdown, no questions. Tell me where the README is, paste the exact command into our chat so I can save it in my notes, and confirm that running it twice in a row is safe (idempotent).
The agent does this for you. Claude writes the kill switch into the README, hands you the one-line command, and confirms idempotency. Save the command in a sticky note or your password manager's secure note. You will not need it often. The one time you do, you will not want to be hunting for it.
When it works.
You'll know the build is real when four things happen in a row, on a single text from your phone:
- The listener picks up your text within five seconds. You can see the trigger fire in your terminal.
- cairns-query runs and returns waypoints from your L1. The Gmail and Calendar MCPs return today's data.
- A short reply composes locally in three to five lines. Plain English first, structured only if it has to be.
- The reply lands on your phone as a normal iMessage. You read it. You move on with your day.
If all four happen, the build is real. Run the trigger from three different places in the next day: from your kitchen, from a walk, from a meeting break. The fact that it keeps working from anywhere with cell service is what proves the pattern is yours.
If you get stuck.
Common failure modes, ranked by how often they bite people on the first build:
- macOS permissions. Full Disk Access or Automation got skipped. The listener either cannot read the Messages database or cannot send a reply. Open System Settings, Privacy & Security, check both. Quit and reopen your terminal after granting; macOS sometimes caches the old state.
- Contact resolution. Your trusted-sender string does not match what Apple actually files the inbound message under. iMessage sometimes routes a message under a phone number when you expected an iCloud address (or vice versa). Send a test, then check the Messages database for the exact string Apple used, and pin that one into the filter.
- MCP outage. Gmail or Calendar throws a transient error mid-reply. The composed reply is missing half its inputs. The listener should still send a reply, but flag in the text that one source was unavailable. If the failure persists, run
/mcpand re-auth the failing connector. - The trigger phrase fires on accident. You typed something close to the phrase in another thread. The listener fired. The fix: pick a longer or more unusual phrase. Plain English is good; plain English you would never accidentally text someone else is better.
- iMessage sync lag. Your Mac is asleep with the lid closed and Messages stopped syncing. Reply is delayed by a minute or more. Plug the Mac in, allow it to stay awake while the display is off, or accept the lag and move on.
- The listener kept running after you closed your terminal. Good news, the kill switch works. Bad news, you forgot it. Pull the one-line command from the README the agent wrote in Step 08.
Still stuck? Post the prompt you ran, the listener log, and what you saw (or did not see) on your phone, in the workshop Slack. Someone in the cohort has hit the same thing.
Where to go next.
You shipped the phone-first pattern. Two natural moves on the shelf, plus one that builds on the same observer shape: