Connect A Mac For iMessage

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.

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.

Local Setup

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

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

Configure the project with non-secret connector metadata:

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:

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:

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