Matilda Worker

The Matilda Worker is a companion macOS menu-bar app, maintained in the ShafiqCo/matilda-worker repository. It runs on a realtor's own Mac, reads their iMessage conversations locally, and streams only the threads they mark as prospects into Matilda. Matilda extracts the qualification details and enriches the matching person in Follow Up Boss under that realtor's own login.

For a step-by-step setup, see Install the Matilda Worker.

How it fits together

1. On the Mac. The worker reads the iMessage database (chat.db) locally and keeps only the threads the realtor marked as prospects.
2. To Matilda. Those threads are posted to /api/worker/ingest over HTTPS, authenticated with the Mac's device key.
3. In Matilda. The webapp extracts budget, intent, timeline, and the other qualification fields.
4. To Follow Up Boss. Matilda creates or enriches the matching person, signed in as that realtor.

The trust boundary is the Mac. Deciding which conversations are prospects happens in the app, and everything else stays local. Extraction and the CRM push happen on the server, using the Follow Up Boss connection the realtor approved in their browser.

Requirements

• macOS 13 or later on Apple silicon, signed in to iMessage
• A Follow Up Boss login for the person using the Mac
• Follow Up Boss sign-in enabled on the Matilda server: FOLLOWUPBOSS_OAUTH_CLIENT_ID and FOLLOWUPBOSS_OAUTH_CLIENT_SECRET set. See Follow Up Boss.
• Two macOS permissions, both requested during setup: Full Disk Access (required, to read the iMessage database) and Contacts (optional, to show names instead of numbers)

Installing and updating

The installer is at matildahq.com/download/mac. It places Matilda Worker in Applications and launches it. The app has no Dock icon; it lives in the menu bar.

Updates are automatic. The app checks hourly and installs new versions itself. Check for Updates… in the right-click menu runs a check on demand.

How connecting works

The only sign-in is Connect Follow Up Boss. There are no tokens to paste and no dashboard account is needed.

1. The worker mints a device key on the Mac and stores it in the login Keychain. Only the key's SHA-256 hash is sent to Matilda, with the Mac's name as its label.
2. Matilda returns a sign-in link and the worker opens it in the browser. The link is valid for 15 minutes.
3. The realtor signs in to Follow Up Boss and approves access. Matilda stores the resulting Follow Up Boss tokens against that device.
4. The browser returns to the app through a matildaworker:// link, and the worker shows Connected as with the realtor's name and account.

From then on the Mac appears on the dashboard Devices page, and every lead it picks up is created and enriched in Follow Up Boss as that realtor. One Mac holds one Follow Up Boss account at a time; Reconnect in Settings switches it.

If the Follow Up Boss connection later expires, the worker shows a Reconnect banner and the Devices page shows needs reconnect. Until the realtor reconnects, synced conversations are still captured in Matilda but nothing is written to Follow Up Boss.

Syncing conversations

Nothing is synced until the realtor marks a conversation. There are two ways to do it.

In the menu. Click the Matilda logo in the menu bar. Conversations lists recent one-to-one threads, each with a round button: red play to start syncing, green stop to end it.

Hands-free. The realtor picks one method, in setup or later in Settings:

Method	Start	Stop
Trigger phrase	Send a message containing a start phrase (default thanks for reaching out)	Send a stop phrase (default best of luck)
Emoji reaction	React to any message in the thread with the start emoji (default 🏠)	React with the stop emoji (default 🏡)

Only the chosen method is live. The other method's values are kept, so switching back restores them.

Rules that apply to both methods:

• Only messages and reactions the realtor sends count. A lead texting the phrase or reacting does nothing.
• One-to-one threads only. A trigger in a group chat syncs nobody.
• With Messages in iCloud on, a reply or reaction from the realtor's iPhone triggers just the same.
• Phrase matching ignores case, punctuation, and extra spaces, and matches anywhere inside a longer message. Several phrases can be listed, one per line.
• Custom emoji reactions need macOS 14.4 or later on the Mac, and a phone that supports emoji tapbacks if reacting from one. Reaction rows themselves are never sent to the server.
• A start trigger only acts on a thread that is not synced and a stop trigger only on a syncing one, so repeating one is harmless.
• Adopting a new trigger never syncs old threads. Only messages that arrive after it was set are scanned.

Each hands-free start or stop posts a macOS notification, Now syncing Jane or Stopped syncing Jane, with an undo button on it.

What gets sent

When a conversation is marked, the worker sends the last 15 or so messages of that thread so the context before the mark is not lost, then keeps streaming new messages. Each sync includes a recent window of the conversation rather than a single line, so Matilda can make sense of replies like "yeah, 2 months". A file watcher picks up new messages within about two seconds.

Conversations that are not synced never leave the Mac. Contact names are sent only for synced conversations.

Sync limit

A Mac syncs up to 5 conversations at a time by default. At the limit, a banner says so, the play buttons are disabled, and a trigger in a new thread posts a Sync limit reached notification instead. Stop a conversation to make room. An Owner can raise the limit for a single Mac on the Devices page; the server-wide default is MATILDA_TRACK_LIMIT.

What Matilda does with synced threads

• Stores messages with source personal_imessage, de-duplicated by GUID
• Runs extraction and records each captured field as a lead event
• Creates the person in Follow Up Boss on first pickup and keeps their details in sync
• Turns what it hears into suggestions: a task, an appointment, a note, a stage move, or a drip campaign. Nothing else reaches the CRM until you apply one.
• Never auto-replies. Worker threads are capture only.

Suggestions and drip campaigns

New suggestions appear as chips above the reply field, newest first.

• Tap a chip to apply it. It shows Added · Undo for a few seconds, then moves to the activity feed, where Undo stays available.
• × dismisses a chip. Matilda suggests it again only after the conversation brings new information about the lead.
• Right-click a task, appointment, or note to change its title, time, or text before applying it.
• Appointment chips disappear once their time passes, and task chips once their due date passes.

Undo deletes the task, appointment, or note, moves the lead back to the stage they were in, or pauses the drip campaign.

The lead's activity panel lists the same suggestions at the top, then Drip campaigns: every active Follow Up Boss action plan with an on/off switch, the ones Matilda suggests first. Switching a plan on enrolls the lead, or resumes a plan they are paused in; a lead is never enrolled twice in the same plan. Follow Up Boss can't take a lead out of a plan, so switching one off pauses it. Lofty's API has no drip campaigns, so Lofty leads get the other suggestions only.

Nothing is suggested until the lead is in the CRM, which happens on their first sync.

The Activity tab in the worker shows the result of each sync: what started or stopped syncing, how many new messages were sent, which fields were captured, and whether the lead reached Follow Up Boss.

The menu-bar app

Left-click the logo for the dropdown: the Conversations and Activity tabs, and a status dot with the usage counter, for example 2 of 5 syncing. Banners appear here when the Mac is not connected, needs reconnecting, is at its limit, or is missing a permission.

Right-click the logo for Sync now, Settings…, Check for Updates…, Open Setup Guide, and Quit Matilda Worker.

Settings has:

Section	What it holds
Account	Who is connected, Reconnect, and Sign out
Start and stop syncing with	The trigger method, its phrases or emoji, and Reset to restore the defaults
Sync	Sync now and the time of the last sync
Permissions	The state of Full Disk Access and Contacts, with a button to fix each
Start at login	On by default. The worker only syncs while it is running.

Sign out stops syncing, removes the Mac from the Devices page, and returns the app to the connect step.

Availability

The worker checks in with /api/worker/link on every sync pass, roughly every 20 seconds while running. The Devices page shows a Mac as online when it has checked in within the last 90 seconds.

Removing a Mac on the Devices page takes effect on its next check-in. The worker stops syncing and asks to be connected again.

Endpoints

All under /api/worker. Everything except device/start requires the device key as a bearer token.

Endpoint	Purpose
POST /device/start	Registers a pending device from its key id and secret hash, returns the Follow Up Boss sign-in link
POST /fub/start	Returns a fresh sign-in link for an already-linked device (Reconnect)
POST /link	Heartbeat. Reports how many conversations are syncing; returns the Follow Up Boss status and the sync limit
POST /ingest	Sends synced conversations; returns captured fields and the Follow Up Boss result per conversation
POST /unlink	Removes the device (Sign out)

Known limitations

• Phone numbers only. Contacts that use an email-only iMessage address are skipped, because Matilda keys people by phone.
• No group chats.
• Some messages may not decode. On recent macOS versions message text is stored in a legacy binary format. A message the worker cannot decode is skipped rather than sent wrong.
• One Follow Up Boss account per Mac.