fgp-imessage

Fast iMessage gateway for macOS via FGP (Fast Gateway Protocol).

292x faster than MCP stdio - eliminates cold-start overhead with persistent daemon.

Performance

Operation	FGP Daemon	MCP Stdio	Speedup
Recent messages	8ms	2,300ms	292x
Unread messages	10ms	2,300ms	230x
Analytics	5ms	2,400ms	480x

Installation

# Build from source
cargo build --release

# Install binaries to PATH
cargo install --path .

# Or copy manually
cp target/release/fgp-imessage /usr/local/bin/
cp target/release/fgp-imessage-daemon /usr/local/bin/
cp target/release/fgp-imessage-client /usr/local/bin/

Requirements

• macOS with Messages.app
• Full Disk Access for Terminal (System Preferences → Privacy & Security → Full Disk Access)
• Automation permission for AppleScript message sending

Quick Start

CLI Mode

# Recent messages
fgp-imessage recent --json

# Unread messages
fgp-imessage unread --json

# Messages with contact
fgp-imessage messages "John" --limit 20 --json

# Send message
fgp-imessage send "Sarah" "Hello!"

# Analytics
fgp-imessage analytics --days 30 --json

Daemon Mode (Fastest)

# Start daemon
fgp-imessage-daemon start

# Use client
fgp-imessage-client recent --params '{"limit":20}'
fgp-imessage-client unread
fgp-imessage-client analytics --params '{"contact":"John","days":30}'

# Bundle multiple queries (reduces round trips)
fgp-imessage-client bundle --params '{"include":"unread_count,recent,analytics"}'

# Stop daemon
fgp-imessage-daemon stop

Daemon Methods

Method	Description	Params
recent	Get recent messages	days (7), limit (20)
unread	Get unread messages	limit (50)
analytics	Messaging statistics	contact, days (30)
followup	Items needing follow-up	days (30), stale (3)
handles	List active handles	days (30), limit (50)
unknown	Unknown senders	days (30), limit (20)
discover	Potential contacts	days (90), min_messages (3)
bundle	Multi-query	include (comma-separated)

CLI Commands (27)

• Messaging: send, send-by-phone, add-contact
• Reading: messages, find, recent, unread, text-search, bundle
• Media: attachments, voice, links, thread
• Groups: groups, group-messages
• Analytics: analytics, followup, reactions
• Discovery: handles, unknown, discover, scheduled, summary
• Contacts: contacts
• RAG: index, search, ask, stats, sources, clear

FGP Protocol

NDJSON over Unix socket at ~/.fgp/services/imessage/daemon.sock:

// Request
{"id":"uuid","v":1,"method":"recent","params":{"limit":20}}

// Response
{"id":"uuid","ok":true,"result":{"messages":[...],"count":20},"meta":{"server_ms":8.2}}

Architecture

┌─────────────┐     ┌──────────────────┐     ┌───────────────┐
│ CLI/Client  │────▶│  FGP Daemon      │────▶│ chat.db       │
│             │     │  (Unix socket)   │     │ (SQLite)      │
└─────────────┘     │                  │     └───────────────┘
                    │  Hot resources:  │
                    │  - SQLite conn   │     ┌───────────────┐
                    │  - Contact cache │────▶│ Messages.app  │
                    │                  │     │ (AppleScript) │
                    └──────────────────┘     └───────────────┘

License

MIT