messenger/CLAUDE.md

@messenger — Multi-Provider Messaging Platform

Workspace Overview

@messenger/
├── codebase/
│   ├── web/                     # React web UI (renamed from frontend-macos-client)
│   └── packages/
│       └── messenger-ui/        # Exportable UI component package (@lilith/messenger-ui)
├── imessage-mcp/                # MCP server — unified provider-aware conversation tools
├── imessage-sync/               # NestJS backend — syncs from macOS agents + email providers
├── imessage-macos/              # Swift agent — runs on Mac, extracts iMessage DB
└── cli/                         # CLI tools

Primary focus: imessage-mcp — the MCP server that exposes conversation data as tools for Claude Code.

---

Architecture

Provider-based system with a unified schema. Each provider (iMessage, Proton Mail, iCloud Mail) stores data in shared tables with a provider discriminator column.

Providers

Provider	Sync Method	Send Method	Config Prefix
imessage	macOS agent push	Pending messages queue	(device-based)
protonmail	IMAP poll via Proton Bridge	SMTP via Proton Bridge	PROTON_*
icloud	IMAP poll via iCloud	SMTP via iCloud Mail	ICLOUD_*

Key Schema Concepts

• conversations.external_id / messages.external_id — provider-specific identifiers (was imessage_id/imessage_guid)
• provider column on conversations + messages — discriminator ('imessage', 'protonmail', 'icloud')
• email_folders + message_folders — email folder structure and message-folder mappings
• contacts.provider_identifiers — JSONB mapping provider-specific IDs per contact

---

imessage-mcp

Stack: TypeScript, @modelcontextprotocol/sdk, pg, tsup, bun

Build & Dev

cd imessage-mcp
bun install
bun run build        # tsup -> dist/index.js
bun run typecheck    # tsc --noEmit

Database

PostgreSQL at localhost:25433/messenger

Table	Purpose
devices	Registered macOS devices
contacts	Contact info (name, phone, email, provider_identifiers)
conversations	Chat threads with provider + external_id
messages	Individual messages with provider discriminator
email_folders	Email folder structure (Inbox, Sent, etc.)
message_folders	Junction: messages belong to folders

MCP Tools

Tool	Description
list_conversations	Browse conversations, optional provider filter
get_conversation	Fetch messages from a specific conversation
get_contact	Look up contact details by name or identifier
search_messages	Full-text search, optional provider filter
get_conversation_stats	Stats with per-provider breakdown
send_message	Send via any provider (iMessage, Protonmail, iCloud)
check_send_status	Check delivery status of queued messages
list_folders	List email folders for a provider
get_folder	List messages in an email folder

Proactive MCP Usage

When working in this project, use mcp__messenger__* tools to query real conversation data for testing and validation.

---

messenger-ui Package

Location: codebase/packages/messenger-ui/ | Published as: @lilith/messenger-ui

Exportable React component library for unified messaging inbox. Components are props-driven (headless pattern) — consumers wire hooks to components.

Build & Dev

cd codebase/packages/messenger-ui
bun install
bun run build        # tsup -> dist/index.js + dist/index.d.ts
bun run typecheck    # tsc --noEmit

Exports

Export	Description
Types	ProviderType, Conversation, Message, EmailFolder, response types
Constants	PROVIDERS, PROVIDER_LABELS, PROVIDER_COLORS, PROVIDER_EMOJIS
Components	MessengerNavBar, ConversationList, ConversationItem, MessageThread, MessagesView, FoldersView, Lightbox
Hook factory	createMessengerHooks(options) — returns all React Query hooks
Utils	formatTime, formatMessageTime, formatDateDivider, getInitials, formatFileSize, attachmentUrl

Hook Factory

createMessengerHooks({
  baseUrl: '',              // e.g. '' for same-origin, '/api' for life-manager
  browsePath: '/api/browse', // prefix for browse endpoints
  adminPath: '/api',         // prefix for admin endpoints
  apiKey: undefined,         // optional X-Service-Key header
})

Provider Icons

Components accept renderProviderIcon?: (provider: ProviderType) => ReactNode prop. Default: unicode emojis from PROVIDER_EMOJIS. Life-manager overrides with @lilith/ui-icons.

---

Other Components

• imessage-sync: NestJS service receiving message data from macOS agents + polling email via IMAP. PostgreSQL + TypeORM.
• imessage-macos: Swift app that reads the local iMessage database and pushes to imessage-sync.
• codebase/web: React web UI for viewing synced conversations (consumes @lilith/messenger-ui).
• codebase/packages/messenger-ui: Exportable UI component package for unified messaging inbox.

currentDate

Today's date is 2026-03-05.