→  

Codex + iMessage

Connect the OpenAI Codex CLI to iMessage through the SealGate gateway. Codex reads and sends texts through the Beeper desktop app on your Mac, with every tool call routed through SealGate's remote MCP endpoint where it is policy-checked and logged. Your iMessage login and history never leave your machine. This repo holds the one-line installer, the Codex config, and an AGENTS.md that teaches Codex how to handle texts safely. The full guide lives at sealgate.ai/connect/imessage/codex.

How it works

flowchart LR
    codex["Codex CLI"] -->|"streamable HTTP MCP"| gw["SealGate gateway<br/>mcp.sealgate.ai<br/>policy + audit"]
    gw -->|"tunnel"| stdiod["sealgate-stdiod<br/>on your Mac"]
    stdiod -->|"stdio MCP"| beeper["Beeper desktop app"]
    beeper --> im["iMessage"]

Loading

1. Codex talks to one remote MCP server, https://mcp.sealgate.ai/mcp, over streamable HTTP with OAuth 2.1.
2. The gateway checks each call against your SealGate policy (for example, read-only for this agent) and writes a metadata audit record.
3. sealgate-stdiod, a small daemon on your Mac, tunnels the call to the Beeper MCP connector running next to the Beeper desktop app.
4. Beeper, signed in to iMessage on that Mac, performs the read or send.

Because the last hop is a tunnel, the same setup works when Codex runs somewhere other than your Mac (a cloud sandbox, a Linux box, a second machine).

Quick start

Requirements: macOS with the Beeper desktop app installed and signed in to iMessage, Codex CLI (npm i -g @openai/codex), and a SealGate account.

1. Install the connector on your Mac

curl -fsSL https://raw.githubusercontent.com/Edison-Watch/app/main/crates/stdiod/scripts/install-beeper.sh | bash -s -- install --install-deps --yes

This installs the Beeper MCP connector plus the sealgate-stdiod tunnel daemon and submits the connector for approval in your SealGate dashboard. Approve it there. Source: Edison-Watch/app, crates/stdiod.

Or run install.sh from this repo, which does step 1 and step 2 together and checks for codex first:

git clone https://github.com/Edison-Watch/codex-imessage.git
cd codex-imessage
./install.sh            # add --dry-run to print the plan without running it

2. Add SealGate to Codex

codex mcp add sealgate --url https://mcp.sealgate.ai/mcp
codex mcp login sealgate      # OAuth 2.1 in the browser
codex mcp list                # sealgate should show as connected

Equivalent TOML in ~/.codex/config.toml (or .codex/config.toml in a project):

[mcp_servers.sealgate]
url = "https://mcp.sealgate.ai/mcp"

3. Ask Codex

Open codex and ask it to list your unread iMessages. The Beeper tools show up through the gateway once the connector is approved in the dashboard.

Try it

$ codex

> Summarise my unread iMessages from today and draft a reply to whichever one needs an answer.

  tool  beeper_search_chats {"unreadOnly": true, "limit": 20}
  tool  beeper_list_messages {"chatID": "imessage:+4479XXXXXXXX"}
  tool  beeper_list_messages {"chatID": "imessage:chat3819XXXXXX"}

  Three unread chats today:

  1. Sam (1:1): asks whether you can move Thursday's call to 4pm. Needs an answer.
  2. "Flat 12" (group): Priya posted the plumber's invoice, Tom says he'll pay half. No action.
  3. Mum: photo of the garden. No action.

  Draft reply to Sam:

    "4pm Thursday works, I'll move the invite."

  Send this to Sam (+44 79XX XXXXXX)? [y/N]

> y

  tool  beeper_send_message {"chatID": "imessage:+4479XXXXXXXX", "text": "4pm Thursday works, I'll move the invite."}

  Sent. Logged in SealGate as beeper_send_message by codex at 09:41.

The draft-then-confirm step comes from AGENTS.md, which Codex reads when it runs inside this repo or any repo you copy the file into. If your SealGate policy sets this agent to read-only, the send is blocked at the gateway and Codex reports the block instead.

What Codex can do with iMessage

Tools exposed through the gateway once the Beeper connector is approved:

Tool	What it does
beeper_search_chats	Find chats by name, participant, or unread state.
beeper_get_chat	Fetch one chat with its participants, to confirm who a message goes to.
beeper_list_messages	Read recent messages in one chat.
beeper_search_messages	Full-text search across chats ("the address Priya sent in March").
beeper_send_message	Send a text to a chat. Can be disabled per agent by policy.
beeper_set_chat_reminder	Set a reminder on a chat instead of replying now.

With those, Codex can:

• Triage unread texts and draft replies in your voice for you to approve.
• Summarise a long group thread so you catch up in seconds.
• Find an address, link, or photo someone texted weeks ago.
• Turn a text conversation into a task, a calendar note, or a code change.
• Set a reminder on a chat you cannot answer yet.

Every call is policy-checked and logged in the SealGate dashboard. Sends can be restricted to read-only per agent by policy, so a coding agent can read context without ever being able to text anyone.

Compared with other Codex iMessage bridges

The other results for "codex imessage" are local bridges that read the Messages database directly. They are a good fit for one Mac and one trusted agent. This route trades a little setup for a control layer.

	Local chat.db bridges (chroming/codex-imessage, dkdc-io/imessage, benelser/imessage-tools)	This repo (SealGate + Beeper)
Message source	~/Library/Messages/chat.db read directly on that Mac	Beeper desktop app signed in to iMessage; login stays on your device
Where Codex can run	The same Mac only	Same Mac, another machine, or a cloud sandbox via the sealgate-stdiod tunnel
Sending	Unrestricted once wired up	Policy-checked per agent; can be read-only
Audit	None built in	Every read and send logged as metadata in the SealGate dashboard
Other networks	iMessage only	Same gateway carries WhatsApp, Telegram, Signal, LinkedIn and others through Beeper
Accounts	None	SealGate account plus Beeper

Configuration reference

OAuth (default), in ~/.codex/config.toml or .codex/config.toml:

[mcp_servers.sealgate]
url = "https://mcp.sealgate.ai/mcp"

API key in the URL path, for clients that cannot complete a browser OAuth flow. Get the key from the SealGate dashboard. It travels in the path, not in an Authorization header, so keep this out of version control:

[mcp_servers.sealgate]
url = "https://mcp.sealgate.ai/mcp/{api_key}/?client=codex"

Both variants, with comments, are in codex/config.example.toml.

mcp.sealgate.ai is the managed release host. Demo and self-hosted orgs run their own gateway host, so substitute your URL where needed.

Security and privacy

What stays on your Mac:

• Your Apple ID and iMessage session (inside Beeper).
• Your message history. Nothing is synced or copied to SealGate.

What leaves your Mac:

• The request and response for each tool call, in transit through the gateway to Codex, policy-checked in memory. SealGate does not store message content.

What is logged in the SealGate dashboard:

• Metadata per call: which tool ran, when, and which agent ran it, plus whether policy allowed or blocked it. Not the text of the messages.

What you control:

• Which agents can see the iMessage connector at all.
• Read-only versus read-and-send, per agent, by policy.
• Revoking the connector or the Codex OAuth grant from the dashboard at any time.

Links

• Guide for this setup: https://sealgate.ai/connect/imessage/codex
• Connect iMessage to other agents: https://sealgate.ai/connect/imessage
• All connectors: https://sealgate.ai/connect
• Docs: https://docs.sealgate.ai
• Installer source: https://github.com/Edison-Watch/app (crates/stdiod)
• Contact: hello@sealgate.ai

License

MIT. Copyright GPU-EVM LTD (Sealgate). See LICENSE.