# Connect A Mac For iMessage

Source: https://docs.generalaugment.com/channels/imessage-mac/
Description: Run a tenant-owned Mac connector so your agent can read, search, draft, and send iMessage with General Augment governance.

iMessage runs through a Mac because Apple does not provide a hosted iMessage API. The
Mac keeps Messages.app permissions, local message history, and the iMessage adapter.
General Augment governs what the agent can read, who it can message, and when approval
is required.

Fast path

## Set up with one command

Run the helper on the Mac signed into Messages.app. It checks local prerequisites,
prints safe connector config, and gives your coding agent a setup prompt without
exposing real handles.

```bash
npx @general-augment/local-imessage setup --project <project-slug> --write-prompt --write-config
```

The generated `general-augment-imessage-connector.json` contains only safe connector
metadata, opaque refs, and governed tool ids. Use it as the checklist for the dashboard
Surfaces starter config or for an admin API project update.

- Checks imsg

- Checks Full Disk Access

- Prints safe refs

- Generates agent prompt

- Keeps sends approval-gated

Agent handoff

## Copy this into your coding agent

Paste this into the coding agent that has access to your app repo and local Mac
terminal.

```text
Set up General Augment local iMessage for my project. Keep real Apple IDs, phone numbers, local Messages paths, transcripts, and tokens out of committed files and chat output. First verify the local Mac has imsg installed and that this terminal or host app has Full Disk Access by running a bounded imsg chats check. Then add a tenant-owned local connector named mac_imessage with capabilities imessage.get_recent_thread, imessage.search_history, and imessage.send_message; use opaque refs such as contact_primary instead of real handles. Enable only the governed General Augment tools imessage_get_recent_thread, imessage_search_history, and imessage_send_message. Require approval for every send. Run the local connector and smoke test read/search behavior first, then only run the controlled send test if I explicitly approve it. Confirm audit/log output is redacted and summarize pass/fail without printing secrets.
```

## Local Setup

Install and verify an iMessage adapter on the Mac, then start the General Augment local
connector:

```bash
uv run python scripts/local-imessage-connector.py
```

Configure the project with non-secret connector metadata:

```yaml
connectors:
  local:
    - name: mac_imessage
      kind: imessage
      url: http://127.0.0.1:8765
      capabilities:
        - imessage.get_recent_thread
        - imessage.search_history
        - imessage.send_message
      policy:
        allowed_contact_refs:
          - contact_primary
        require_approval_for_send: true

tools:
  builtin:
    - imessage_get_recent_thread
    - imessage_search_history
    - imessage_send_message
```

For hosted deployments, point `url` at a tenant-operated secure relay, tunnel, or
private network endpoint.

## Tools

| Tool | Behavior |
| --- | --- |
| `imessage_list_threads` | Lists allowed thread summaries. |
| `imessage_get_recent_thread` | Reads recent history for an allowed contact or thread. |
| `imessage_search_history` | Searches allowed local history. |
| `imessage_draft_reply` | Drafts without sending. |
| `imessage_send_message` | Sends only after General Augment approval. |

Use opaque contact and thread refs. Do not put real phone numbers, Apple IDs, local
database paths, or message transcripts in committed config.

## Smoke

Keep private values in your local shell:

```bash
export GENAUG_LOCAL_IMESSAGE_TEST_CONTACT_REF=contact_primary
export GENAUG_LOCAL_IMESSAGE_THREADS_JSON='{"contact_primary":"chat_id:<local chat id>"}'
uv run python scripts/local-imessage-smoke.py
```

The smoke verifies the adapter exists, starts the local connector, calls the governed
recent-read and search-history tools, and checks that audit output is redacted. Enable
the controlled send portion only when you are ready:

```bash
export GENAUG_LOCAL_IMESSAGE_SMOKE_SEND=true
export GENAUG_LOCAL_IMESSAGE_ENABLE_SEND=true
uv run python scripts/local-imessage-smoke.py
```