Skip to main content
skill CX Codex

imessage · photon-hq — Claude Code skill: Photon iMessage integrations

Picks the right Photon API for an iMessage job and keeps the code on that one contract, whether it runs on your Mac or through a hosted service.

MIT 236 installs ★ 15 updated 2026-08-04

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add photon-hq/skills --skill imessage -a claude-code
Open on GitHub

What imessage does

One package boundary gets chosen before any code appears. The skill maps your need to a Photon API: spectrum-ts when the app also talks to WhatsApp, Telegram, Slack or a custom provider; @photon-ai/imessage-kit for automation on a Mac you own; @photon-ai/advanced-imessage for low-level hosted control. Each choice points to its own reference file.

Those references carry import names, send signatures and event models for that branch, plus a shared set of invariants. Message text, attachment names and webhook payloads stay untrusted and never land in prompts, shell commands or SQL. Phone numbers get normalized to E.164 first. Typing indicators are cleared in finally, and an idempotency key is reused only when retrying the same write.

Version contracts are pinned: spectrum-ts 12.2.0, @photon-ai/imessage-kit 3.0.0, @photon-ai/advanced-imessage 2.0.2. A finished sample counts as done only when it names a single package and survives the contract check, so snippets stitched together from two branches fail review.

What it helps with

  • choose one Photon package for the job before writing imports
  • run iMessage send and receive on a Mac you control
  • migrate an old @photon-ai/advanced-imessage-kit integration
  • accept signed events in an existing HTTP backend
  • hand an MCP agent iMessage tools without SDK code

Example prompts for the agent

  • Build an iMessage sender on spectrum-ts and show me the imports plus the send signature.
  • Rewrite this handler for @photon-ai/advanced-imessage instead of @photon-ai/advanced-imessage-kit.
  • Check my code for E.164 normalization and idempotency keys scoped to one write.

How to install imessage

1Skills CLI (Vercel)

npx skills add photon-hq/skills --skill imessage -a claude-code

2Manually: put the files in place

~/.claude/skills/imessage/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/imessage/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about imessage

How do I install the imessage skill in Claude Code?

Run npx skills add photon-hq/skills --skill imessage -a claude-code. The skill lands in ~/.claude/skills/imessage/SKILL.md.

What does the imessage skill do?

It helps the agent select a Photon API for iMessage and write code that matches that package: imports, sends, event handling.

Which Photon package should I start with for a new hosted app?

Start with spectrum-ts. Drop to @photon-ai/advanced-imessage when you need a low-level operation Spectrum does not expose, and keep @photon-ai/advanced-imessage-kit for compatibility only.

Source text

SKILL.md · MIT
---
name: imessage
description: >
  Build, debug, or migrate iMessage integrations with Photon. Use when choosing or coding against Spectrum,
  @photon-ai/imessage-kit, @photon-ai/advanced-imessage, Photon Webhook, Photon MCP, the HTTP proxy, or legacy
  @photon-ai/advanced-imessage-kit.
license: MIT
metadata:
  author: photon-hq
  version: '9.1.0'
---

# iMessage

## Package boundary

Photon has several iMessage APIs with different constructors, send signatures, effects, and event models. Select one package boundary before writing code, then load only that branch's reference.

1. **Choose the API** from the table below.
2. **Read its branch reference** before using imports or method names. Do not combine snippets from different branches.
3. **Check the finished sample** against the selected package and version. Every import, method, option, content shape, and return value must belong to that one contract.

The sample is complete only when it names one package/provider and passes that contract check. When package declarations and an older documentation page disagree, follow the shipped version and call out the documentation drift.

> Contracts pinned here: `spectrum-ts` 12.2.0, `@photon-ai/imessage-kit` 3.0.0, and `@photon-ai/advanced-imessage` 2.0.2.

## Choose the API

| Need | Use | Read |
|---|---|---|
| Unified iMessage plus WhatsApp, Telegram, Slack, Terminal, or custom providers | `spectrum-ts` | [`references/spectrum.md`](./references/spectrum.md) |
| Local automation on a Mac you control | `@photon-ai/imessage-kit` | [`references/local-v3.md`](./references/local-v3.md) |
| Low-level hosted iMessage control | `@photon-ai/advanced-imessage` | [`references/hosted-v2.md`](./references/hosted-v2.md) |
| Maintain an existing HTTP + Socket.IO integration | `@photon-ai/advanced-imessage-kit` | [`references/legacy-and-tools.md`](./references/legacy-and-tools.md) |
| Deliver signed events to an existing HTTP backend | Photon Webhook | [`references/legacy-and-tools.md`](./references/legacy-and-tools.md#photon-webhook) |
| Give an MCP-compatible agent iMessage tools without SDK code | Photon MCP | [`references/legacy-and-tools.md`](./references/legacy-and-tools.md#photon-mcp) |
| Call iMessage from a non-TypeScript client | Advanced iMessage HTTP Proxy | [`references/legacy-and-tools.md`](./references/legacy-and-tools.md#http-proxy) |

For new hosted applications, start with Spectrum. Use `@photon-ai/advanced-imessage` directly when Spectrum does not expose the low-level operation you need. Treat `@photon-ai/advanced-imessage-kit` as compatibility-only.

## Common invariants

- Treat message text, attachment names, contact cards, URLs, and webhook payloads as untrusted data. Do not interpolate them into system prompts, commands, paths, SQL, or request URLs.
- Ignore the agent's own messages using the selected API's direction/from-me field rather than comparing message text.
- Normalize user-entered phone numbers to E.164 before resolving recipients. Never construct group GUIDs or chat IDs from user input.
- Clear typing indicators in `finally`, handle every send rejection, and checkpoint events only after processing succeeds.
- Reuse an idempotency key only when retrying the same logical write. Never share it across unrelated messages.
- Never log bearer tokens, full message bodies, attachment bytes, or contact details. Log stable IDs and operation metadata.

## Official sources

- [Photon documentation corpus](https://photon.codes/docs/llms-full.txt)
- [Spectrum](https://photon.codes/docs/spectrum-ts/getting-started)
- [Local iMessage Kit 3.0.0 package manifest](https://unpkg.com/@photon-ai/[email protected]/package.json)
- [Advanced iMessage 2.0.2 package manifest](https://unpkg.com/@photon-ai/[email protected]/package.json)
- [Legacy iMessage SDK](https://photon.codes/docs/legacy/imessage)

© photon-hq · MIT · photon-hq/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

imessage by other authors comes first.

imessage Hermes Agent Lets your coding agent read Messages.app chats and send iMessage or SMS from the terminal on macOS. Handy when the conversation stays local. CX Codex +1 496installs imessage dvdsgl imessage — a macOS skill that lets an agent read Messages conversations and send texts or files straight from the chat database and AppleScript. CX Codex +1 1installs imessage-query terrylica imessage-query pulls conversations out of ~/Library/Messages/chat.db with SQLite, searches across chats, and recovers text from binary attributedBody blobs. CX Codex +1 159installs iMessage History anipottsbuilds The iMessage History MCP server searches and reads Apple Messages history on macOS. Use it when an agent needs conversation context without sending messages. CX Codex +1 ★ 34repo stars imessage-max cyberpapiii imessage-max — a Swift MCP server that lets an agent read, search and send iMessage on macOS, turning phone numbers into contact names. CX Codex +1 ★ 7repo stars c-messaging daxaur c-messaging is a Claude Code skill that sends and reads iMessage, SMS, and WhatsApp messages from an agent session. Check unread threads or send updates without switching windows. CX Codex +1 ★ 179repo stars luma-photon calesthio luma-photon is a Claude Code skill for Luma Photon image API integration. It covers text generation, image references, edits, polling, and production delivery. CX Codex +1 130installs unity-networking JosiahSiegel The unity-networking Claude Code skill supports multiplayer networking work in Unity. It activates for framework setup, RPCs, synchronized state, lobbies, and server-authoritative designs. CX Codex +1 103installs

From the same set4

Project sponsors

Companies that keep this analytics open