Skip to content

README.md

Latest commit

 

History

History
127 lines (93 loc) · 3.83 KB

README.md

File metadata and controls

127 lines (93 loc) · 3.83 KB

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