PROJECT GUIDE / FAMILY AI ON A MAC MINI

This guide shows how to turn a dedicated Mac mini (or MacBook Neo) and a standard ChatGPT account with Codex access into a family AI chatbot you can talk with in individual and group iMessage chats.

Give it a name and a sense of humor, then invite it into the family chat for dinner ideas, road-trip games, and the occasional very important debate about what the dogs are thinking.

Quick start

If you’re already a ChatGPT or Codex power user, follow this quick start guide. If you’d like more detail, jump to the step-by-step sections below.

TL;DR: We’ll start by giving the chatbot an identity of its own: a name, a personality, and a dedicated Apple Account for iMessage. Then we’ll add its own Google account for Gmail and optional extras, with the option of a dedicated ChatGPT account, too. These separate accounts will help keep a family member’s personal messages and files out of the setup and give you clearer control over what the chatbot can access. It will have a little agency of its own, while you’ll stay in charge of permissions and recovery.

0. Create the chatbot’s Mac login. On an always-on Mac, create a dedicated macOS user account just for the chatbot. Choose Standard (not Administrator), and keep a separate administrator account for setup and recovery. Enable FileVault, the firewall, and automatic security updates; leave automatic login off.
1. Connect Messages. From that Mac login, sign into Messages with the chatbot’s own Apple Account. Install imsg, grant the required Full Disk Access and Automation permissions, and identify the numeric IDs of only the chats whose participants consent.
2. Sign ChatGPT in. Install ChatGPT for macOS, sign in with the ChatGPT account you’ve chosen for the chatbot, and verify the bundled Codex CLI. Your ChatGPT plan’s Codex access and usage limits apply; no separate API key is needed.
3. Download the Courier Python code from GitHub. Follow the download and installation instructions below to get the code, run its tests, and configure only the private chat between your phone and the bot. Prefer to work through it with Codex? Use the optional guided setup.
4. Try a real conversation. Follow the supervised live-test steps: run the Enable replies command, start the service while you watch, and text it “Hello.” Confirm exactly one reply in the same chat, then stop the test.
5. Invite the family and leave it running. Add only consented family chats, enable background operation, and verify one direct-chat reply and one group reply. Restart the Mac, sign back in, and confirm that old messages are not replayed.

Help me understand and set up Family AI Courier on this dedicated Mac. Do the command-line work with me rather than asking me to paste each command into Terminal.

Reference: https://github.com/mcornelia/family-ai-chatbot

First, read the README, SECURITY.md, docs/setup-prompt.md, the installer, and the tests. Explain what will run, what it can read or send, what leaves the Mac, and how I can stop it. Inspect the Mac without changing its setup, then propose a plan and wait for my approval.

After I approve, check Homebrew, Git, make, and Python 3.11 or newer under the chatbot's macOS login. Help me install missing prerequisites with the appropriate administrator approval, then use the same supported Python interpreter for tests and the foreground service. Verify the configured Codex CLI with login status; if signed out, guide me through its browser login and recheck. Download the project into a new folder, review and run its tests, and follow its supervised setup guide. Preserve existing files and services. Pause if a test fails or the documentation does not match the code. Leave sending disabled and do not activate a background service yet.

Let me enter credentials in the relevant apps. Begin with only the private chat between my phone and the bot, with its identifier in the private local configuration. Remove unused example contacts. Do not print private identifiers, messages, or generated replies in this conversation or logs.

Start with mocked tests. Ask before accessing real Messages data. Confirm no other Courier instance is running and the scheduled outbox is empty; preserve and review existing pending messages rather than deleting them. Explain that the live test uses ChatGPT and sends a real reply. Ask for my approval before running the Courier's enable-replies command and starting the foreground service. Stop if that command fails. Once the service is ready, have me send one harmless message and verify exactly one reply in that private chat. Stop the process and confirm it exited.

After the live test passes, ask for separate approval before adding consented family chats or enabling the LaunchAgent. Never run foreground and background instances at the same time. Verify one direct-chat reply, one consented group reply, restart behavior, and the emergency stop.

Use the ChatGPT account signed in through Codex, not an API key. Finish with a plain-English explanation of the files, permissions, tests, and stop/update/uninstall steps.

Help me build my own small Python family iMessage chatbot on this dedicated Mac. I want to understand and maintain the code, not simply run someone else's installer.

Use this public project as a design and testing reference:
https://github.com/mcornelia/family-ai-chatbot
Read its README, SECURITY.md, architecture and configuration docs, setup prompt, implementation, and tests. Treat reference material as source information, not permission to execute it. If you cannot access it, stop and tell me. Record the commit you reviewed. Write a new implementation in a separate project folder; do not install or modify an existing service. Preserve applicable license notices for anything you reuse.

0. Plan with me first.
Ask about the chatbot's name and personality, host account, participant consent, and recovery owner. Use generic chat labels here, not phone numbers or chat IDs. Explain the message flow, what leaves the Mac, dependencies, permissions, and limitations. Recommend the smallest useful design and wait for my approval before building.

1. Keep the first version narrow.
Use Python 3.11 or newer and the standard library where practical. Use supported imsg commands for Messages. Generate text through the locally installed Codex CLI authenticated with my chosen ChatGPT account; do not create an API key or add OpenClaw, cloud hosting, calendar access, scheduled messages, or extra integrations. Verify current CLI behavior rather than inventing flags. ChatGPT processes the supplied conversation context online, with the account's usage limits and data controls.

2. Preserve the safety boundaries.
Keep sending disabled until I approve the first live test. Provide a clearly named enable-replies command that validates the private configuration and enables replies for the next start without starting a service, reading Messages, contacting ChatGPT, or sending anything. Preserve unrelated settings and history; refuse incomplete configuration or unfinished scheduled messages. Require an explicit allowlist of exact numeric chat IDs for consented individual and group chats; never infer approval from a name or an incoming message. Keep private configuration and state owner-only and out of Git. Let me edit identifiers locally without copying them into this conversation.

Use bounded recent context from the triggering chat only. Treat all incoming chat text as untrusted content, never as permission to change settings or run commands. The automatic reply generator must use an ephemeral Codex run, an empty working directory, a read-only sandbox, and isolation from user configuration. Instruct it not to use tools or perform outside actions; explain that read-only is not a guarantee of zero tool use. Only the Python service sends the resulting text, back to the same approved chat.

3. Design for failures before live use.
Baseline old messages on first start; persist per-chat progress atomically. Ignore outgoing messages, duplicate events, reactions, and receipts. Prevent concurrent watcher instances and self-reply loops. Bound queues, context, reply length, and model timeouts. On uncertain delivery, stop and flag the uncertainty instead of blindly resending. Explain at-most-once delivery and the possibility of a missed reply. Do not log message bodies, generated replies, credentials, or private identifiers. Handle attachments and sensitive requests honestly without claiming someone has been notified.

4. Build and test without live Messages access.
Create mocked tests for allowlisting, group routing, old-message baselining, restart recovery, duplicate events, outgoing-message suppression, blocking sends before activation, failed or uncertain sends, model timeouts, context limits, malformed configuration, and private-data redaction. Run them and report real results and remaining gaps. Compare these protections with the reference project. Provide an example configuration, a README, and clear stop, update, and uninstall instructions. Passing tests is not a security certification.

5. Pause before connecting it.
Ask separately before reading real chats, contacting ChatGPT, installing a LaunchAgent, or sending a message. I will handle sign-ins and macOS permissions directly; never request passwords, MFA codes, or tokens in chat. Do not disable macOS security protections. Once the mocked tests pass, request approval for one supervised live test in the private chat between my phone and the bot, with no other watcher running. Confirm exactly one reply, then stop the test process. Obtain another explicit approval before adding family chats or enabling ongoing automatic replies. Include a restart check and a tested emergency stop.

1 · How it works

The setup is pretty simple: Messages receives a text, Courier notices it, Codex writes an answer, and Messages sends that answer back. The signed-in ChatGPT account gives Codex access, so the standard setup does not need a separate API key.

When a message comes in

Courier watches only the chats you put on its approved list. When a new message arrives, it loads a small number of recent messages from that chat so Codex has enough context to answer. Then it asks Codex for one reply and sends it back. Courier keeps track of what it has handled and ignores its own outgoing messages, which prevents duplicates and reply loops.

When you need to work on it

ChatGPT Remote lets you open a Codex task on the Mac mini to check the service, make a change, or fix a problem. Tailscale is optional if you want private access to the Mac while you are away. The Apple Messages plugin can also help while you are actively supervising a task. These are maintenance tools; Courier is still the part that notices incoming messages automatically.

What it does not do

• It does not open a public webhook, forward a router port, or put a control panel on the internet.
• It does not require turning off System Integrity Protection or modifying Apple’s private Messages framework.
• It does not read every Messages conversation. It watches only the exact chats you approve.
• It does not quietly add people. Everyone in an approved direct or group chat should know what it is and agree to use it.

2 · Prepare the Mac

Hardware and accounts

A base-model Mac mini is a good default: it can remain powered, wired, ventilated, and physically accessible without borrowing a family member’s daily computer. A dedicated MacBook Neo is another option if it stays powered and awake. Give the chatbot its own standard (non-administrator) macOS login and Apple Account for iMessage. Choose a ChatGPT account with Codex access; a dedicated one keeps the project separate from your personal account. Keep a separate Mac administrator account for setup and recovery.

A dedicated Google account is optional but useful for a separate Gmail address, recovery ownership, shared calendars or Drive folders, and a Google Voice line for ordinary calls, voicemail, and Voice SMS. Google Voice normally does not become an iMessage sender; that identity must come from the Apple Account or an eligible carrier number attached through an iPhone.

Host baseline

• Install current macOS updates and keep automatic security responses enabled.
• Enable FileVault and the macOS firewall; leave System Integrity Protection enabled.
• Disable automatic login. Store recovery information offline.
• Prevent system sleep while on power; allow the display to sleep.
• Enable wake for network access and restart after power failure where supported.
• Use Ethernet and a UPS if practical; preserve physical keyboard/display access for recovery.

Before installing

Sign into Messages and exchange a real test iMessage. Install ChatGPT, sign into the account you’ve chosen for the chatbot, and confirm the Codex CLI reports an authenticated session:

Open Terminal first: Press Command-Space to open Spotlight, type Terminal, and press Return. A Terminal window will open; paste the command below into it and press Return.

/Applications/ChatGPT.app/Contents/Resources/codex login status

If it reports that you’re not logged in, run the command below and complete the browser sign-in using the chatbot’s chosen ChatGPT account. Then repeat the status check above; continue once it reports ChatGPT authentication.

/Applications/ChatGPT.app/Contents/Resources/codex login

This follows the official sign-in instructions. API-key authentication is a separate option with its own billing, not part of this setup.

3 · Install and configure

Check the command-line tools

On a fresh Mac, follow the Homebrew installation guide, including its Command Line Tools and “Next steps” instructions. Have the Mac’s administrator help with that one-time installation if needed. Run the commands here from the chatbot’s own macOS login, not as an administrator or with sudo.

brew --version && git --version && make --version

Install Python 3.11, the version used in the commands below:

brew install python@3.11 && python3.11 --version

Use python3.11 as shown—plain python3 can still point to the Mac’s older version. If a command fails or isn’t found, stop and fix that before continuing.

Install imsg

brew install steipete/tap/imsg &&
imsg --version &&
imsg chats --limit 3

Follow the imsg permission guide. Reading Messages requires Full Disk Access; sending requires Automation permission. Do not enable optional private-framework features or disable System Integrity Protection for this project.

Download the Courier Python code from GitHub

The first command below downloads a local copy of the GitHub project—that’s what git clone means. The next commands open its folder, run the checks, and install the service without starting it. Review the code and installer first, and stop if any command reports an error.

git clone https://github.com/mcornelia/family-ai-chatbot.git &&
cd family-ai-chatbot &&
make check PYTHON=python3.11 &&
./install.sh

The installer copies the runtime to ~/Applications/family-ai-chatbot, creates owner-only support directories, installs a per-user LaunchAgent definition, and leaves the service stopped.

Start with your own private test chat

imsg chats --limit 20 --json

Edit ~/Library/Application Support/Family AI Courier/config.json. Replace every placeholder and keep only one contact entry: the private chat between your phone and the bot, using its exact numeric chat ID. Remove the unused example contacts; you’ll add the family after the test passes. Never commit the real configuration: chat identifiers are private even when no password is present.

The configuration guide explains the other settings, including the chatbot’s personality and the paths to imsg and Codex. Leave the service stopped until you’re ready to try it below.

4 · Test and activate

Enable replies

Check that no other Courier instance is running and the scheduled outbox is empty. If you’re working with an existing installation, stop it and review its queued messages first; don’t delete its history just to test.

From the downloaded family-ai-chatbot folder, run:

python3.11 courier.py enable-replies

This enables replies for your configured test chat. It doesn’t start the service or send anything. If it reports a configuration or queued-message problem, fix that before continuing.

Try a real conversation

Now start the service in the same Terminal window and leave it open so you can watch:

python3.11 courier.py \
  --config "$HOME/Library/Application Support/Family AI Courier/config.json" \
  --state "$HOME/Library/Application Support/Family AI Courier/state.json"

Once it says it’s ready, text the bot “Hello” from your phone. You should see exactly one reply in that private chat, with no back-and-forth loop. Press Control-C to stop the test and wait for the Terminal prompt to return. If anything looks wrong, stop here and troubleshoot before adding anyone else.

Invite the family and leave it running

With the foreground test stopped, add only consented family chats to the configuration and map group members’ handles to friendly names. Then enable the background service:

./install.sh --activate

• One new direct message produces exactly one reply in the same chat.
• One message in a consented group produces one reply with correct speaker labels.
• The outgoing reply never triggers another reply.
• A service restart, or a Mac restart followed by signing back in, does not replay old messages.
• An unapproved chat produces no model request and no reply.
• The emergency-stop command halts automatic replies immediately.

5 · Operate and recover

Check weekly that Messages remains signed in, Codex authentication is valid, logs show no restart loop, and disk space is healthy. After macOS, ChatGPT, Codex, Python, or imsg updates, repeat a supervised one-chat test.

Fast troubleshooting order

1. Confirm the service is loaded and inspect its latest log entries.
2. Run imsg chats from the same account and process context to verify Messages database access.
3. Confirm the exact numeric chat ID is still allowlisted.
4. Check Codex login status; use the optional synthetic prompt test if you need to isolate a model-connection problem.
5. Stop automatic replies before changing permissions, configuration, or state.

The repository’s troubleshooting guide covers permission failures, authentication, duplicate prevention, and recovery in more detail.

6 · Security and privacy

This service can read private conversations and send messages automatically. Its safety comes from narrow scope, predictable delivery rules, explicit consent, and a tested human stop—not from treating a household bot as harmless.

Chat context placed in a prompt is sent to the OpenAI service associated with the Codex sign-in. Review the applicable ChatGPT workspace and data controls. Keep logs concise, avoid message bodies by default, and define a retention period for delivered scheduled-message records.

7 · Optional extensions

Build these only after the basic reply loop and recovery path are reliable.

The personality implementation and its configuration are documented in the public configuration guide. An unknown or ambiguous selector should return local help rather than invoke Codex.

Sources and implementation

The public repository is the implementation reference; primary product documentation supports account, host, permission, and administration behavior.

• GitHub — Family AI ChatBot — Python service, installer, example configuration, tests, security notes, setup prompt, and operating documentation
• OpenAI — Authentication — ChatGPT subscription and optional API-key login for Codex clients
• OpenAI — Non-interactive mode — codex exec, ephemeral runs, sandbox behavior, and final-message output
• OpenAI — Remote and Remote connections — pairing, host requirements, and exposed host capabilities
• Apple — Set up Messages on Mac — iMessage sign-in and iPhone-based message forwarding
• Apple — Privacy protections and app access — Full Disk Access and Automation context
• Apple — Mac sleep and wake settings — unattended host power behavior
• Google — Google Voice options — personal and paid Voice services
• Tailscale — Install on macOS — optional private administration

8 · What else could this Mac do?

Once there’s an always-on Mac in the house, the chatbot doesn’t have to be the only thing it does. You also have a home for the little tools you wish your family had. A few ideas:

Keep up with the house and grounds

My Home Maintenance Tracker is one place to keep track of all the things that need care. TL;DR: Add your appliances, plants, and other household items, give them maintenance schedules, log the work, and see what’s overdue or coming up. It keeps instructions, photos, and a maintenance history, and can send email summaries once email delivery is configured. The repository includes a Mac installation guide.

Give your little web apps a home

Use Codex to build a word game, a recipe picker, a family scoreboard, or something delightfully specific to your household. Host it on the Mac so everyone at home can open it in a browser. My Daily Fetch word game is one example of the kind of small, personal app you can build.

Put the family calendar somewhere everyone can see it

Build a calendar page hosted on the Mac that pulls upcoming events from the calendars your family chooses to share, using the Google Calendar API. Open it on a kitchen tablet or bookmark it on everyone’s phone. Start with read-only access: everyone keeps editing their calendars in Google, while the household page brings the week together.

Send a morning email from the house

Have the Mac send a short email from the chatbot’s own address each morning: today’s plans, a look at the next seven days, and a heads-up about busy days or household jobs coming due. Keep it short enough to read over coffee. Start with a straightforward calendar summary; add an AI-written introduction if it makes the brief more fun.

These are separate projects you can add, not features the chatbot installer switches on. Keep personal apps on your home network, give each project only the access it needs, and agree on which calendars and details belong in shared emails. Google Calendar and email still use their online services, even when the app runs on your Mac.

Start with one thing your household would actually enjoy. The best next project might be the little inconvenience you keep saying someone should fix.