Skip to content

feat(gateway): add iMessage platform adapter#3687

Closed
KumarVandit wants to merge 1 commit into
NousResearch:mainfrom
photon-hq:feat/imessage
Closed

feat(gateway): add iMessage platform adapter#3687
KumarVandit wants to merge 1 commit into
NousResearch:mainfrom
photon-hq:feat/imessage

Conversation

@KumarVandit

@KumarVandit KumarVandit commented Mar 29, 2026 •
edited
Loading

Copy link
Copy Markdown

Summary

What

Adds iMessage as a first-class messaging platform in the Hermes gateway, supporting both local macOS mode (SQLite polling + AppleScript) and remote mode via the Photon advanced-imessage-http-proxy.

  • Local mode: Polls ~/Library/Messages/chat.db for inbound messages, sends via AppleScript. macOS only, no external dependencies.
  • Remote mode: Communicates with a Photon Kit server through a centralized HTTP proxy. Works from any OS. Supports text, files, images, audio, tapbacks, typing indicators, message effects, message queries, chat history, attachment download, and iMessage availability checks.

Why

Hermes supports Telegram, Discord, Slack, WhatsApp, Signal, and SMS — but not iMessage, despite it being the default messaging platform for hundreds of millions of Apple users. This gap means macOS users can't interact with their Hermes agent through the app they use most. Adding iMessage brings Hermes to the platform where many users already spend their time, and the remote mode via Photon makes it accessible without requiring the user to run Hermes on a Mac.

Changes across 23 files

Area Files What
Adapter gateway/platforms/imessage.py Full IMessageAdapter implementation (~1000 lines)
Config gateway/config.py Platform.IMESSAGE enum, env var overrides, connectivity gating
Gateway gateway/run.py, gateway/session.py, gateway/channel_directory.py Adapter creation, authorization maps, PII-safe list, session discovery
Agent agent/prompt_builder.py, agent/redact.py Platform hints, redaction patterns
Tools tools/send_message_tool.py, tools/cronjob_tools.py, toolsets.py Send routing, cron delivery, hermes-imessage toolset
CLI hermes_cli/gateway.py, hermes_cli/status.py, hermes_cli/main.py, hermes_cli/tools_config.py, hermes_cli/skills_config.py Setup wizard, status display, CLI parity
Tests tests/gateway/test_imessage.py 48 unit tests covering config, helpers, integration points, CLI parity, event contract
Docs website/docs/user-guide/messaging/imessage.md, website/docs/user-guide/messaging/index.md, website/docs/reference/environment-variables.md, README.md, AGENTS.md, CONTRIBUTING.md Full setup guide, env var reference, platform listings

How to test

Remote mode (any OS)

# Add to ~/.hermes/.env
IMESSAGE_SERVER_URL=https://<your-id>.imsgd.photon.codes
IMESSAGE_API_KEY=<your-photon-api-key>
IMESSAGE_ALLOWED_USERS=+15551234567

hermes gateway run
# Send a message from the allowed number — Hermes will respond

Local mode (macOS only)

# Add to ~/.hermes/.env
IMESSAGE_ENABLED=true
IMESSAGE_ALLOWED_USERS=+15551234567

# Grant Full Disk Access to Terminal in System Settings → Privacy
hermes gateway run

Unit tests

pytest tests/gateway/test_imessage.py -v

Platforms tested

  • macOS (remote mode with Photon Kit server)
  • macOS (local mode)

@KumarVandit KumarVandit marked this pull request as ready for review March 29, 2026 09:07
@KumarVandit

KumarVandit commented Mar 30, 2026

Copy link
Copy Markdown
Author

Hi team! Just wanted to flag this PR for review when you get a chance. It adds iMessage as a new gateway platform (local macOS + remote via Photon proxy), with 48 tests and full docs. Happy to address any feedback. Thanks!

@KumarVandit
feat(gateway): add iMessage platform adapter
f8f1945 
Adds iMessage as a first-class messaging platform with two modes:

- Local (macOS): polls ~/Library/Messages/chat.db for inbound messages,
  sends via AppleScript. Handles images, audio, and file attachments.
- Remote (any OS): talks to Photon advanced-imessage-http-proxy over HTTP.
  Supports text, replies, effects, file/image/audio sending, tapbacks,
  typing indicators, mark read/unread, message search, chat history,
  attachment download, and iMessage availability checks.

Integration touches: Platform enum, gateway runner, session PII, prompt
hints, toolsets, cron delivery, send_message tool, channel directory,
CLI setup wizard, CLI status, and documentation.
@KumarVandit

KumarVandit commented Mar 31, 2026

Copy link
Copy Markdown
Author

Hey @rewbs — would you mind taking a look when you get a chance? This adds iMessage as a new gateway platform. Happy to address any feedback!

@teknium1 teknium1 mentioned this pull request Apr 9, 2026
Merged
4 tasks
@teknium1

teknium1 commented Apr 9, 2026

Copy link
Copy Markdown
Contributor

Closing in favor of #6437 which landed BlueBubbles as the first iMessage backend. Your dual-mode approach (local SQLite + Photon remote) covered interesting ground — if Photon remote mode is desired as a second backend, we'd consider it separately. Thank you @KumarVandit!

@teknium1 teknium1 closed this Apr 9, 2026
@fortunexbt

fortunexbt commented Apr 17, 2026

Copy link
Copy Markdown

Status update: PR/issue #3687 is currently closed (closedAt: 2026-04-09) and was explicitly closed in favor of #6437, where BlueBubbles became the primary iMessage backend. Net: this change is not merged as proposed; next step is to track any Photon-remote iMessage follow-up separately if that functionality is still needed.

@alt-glitch alt-glitch mentioned this pull request Apr 30, 2026
Open
8 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@KumarVandit @teknium1 @fortunexbt