Local-first macOS messaging assistant for iMessage and personal WhatsApp threads, relationship-aware AI replies, and guarded autopilot.
- Real iMessage Thread Picker — Reads local iMessage chats from the Mac Messages database and lets you search by name, handle, group, or recent text
- Personal WhatsApp Thread Picker — Connects to a local whatsmeow-based bridge, reads WhatsApp chats from SQLite, and sends through the bridge REST API
- Contact Name Resolution — Resolves phone numbers and Apple IDs to Apple Contacts names when macOS permissions allow it
- Chat-First Workbench — Shows the selected conversation as message bubbles instead of forcing pasted context or manual transcript entry
- One-Button Bot Mode — Select a chat, press Start bot, and SocializeAI watches that thread without stopping other running chats
- 10-Second Pending Send — Before a live bot reply sends, the app shows the generated text with Cancel, Regenerate, and Send now
- Activity Log — Shows what the bot is doing: queued replies, held messages, sends, blocked attempts, and permission issues
- Global LLM Context — Adds a reusable Settings prompt for your personal facts, links, and standing style instructions on every generated reply
- Permission Modes — Choose Extra safe, Safe, Auto review, or Dangerously skip depending on how much approval you want before sends
- Screen-Share Privacy Mode — Blurs names, phone numbers, message text, inputs, activity details, and audit logs while leaving controls usable
- OpenAI + Local Model Routing — Supports OpenAI, Ollama, and OpenAI-compatible local servers
- WhatsApp Bridge Settings — Supports the maintained
verygoodplugins/whatsapp-mcpbridge by default, with the WhatsApp Business Cloud API path still available as an advanced connector - Local-First State — Stores settings, contacts, relationship memory, and audit events locally through the Electron app
- Safety Gates — Dry run, human approval, opt-out, sensitive-topic blocking, audit logs, and per-chat autopilot allow-listing
- macOS with Messages.app signed in
- Node.js 20+
- npm
- OpenAI API key, Ollama, or another OpenAI-compatible local model server
- Optional for WhatsApp: internet access for first-time bridge setup
git clone https://github.com/markksantos/SocializeAI.git
cd SocializeAI
npm installnpm run desktopFor active development with Vite hot reload:
npm run devnpm run package:mac
open release/mac-arm64/SocializeAI.appSocializeAI uses local macOS data and automation, so permissions matter.
Grant Full Disk Access to the app that launches SocializeAI:
- Development: grant it to the terminal app running
npm run desktopornpm run dev - Packaged app: grant it to
SocializeAI.app
For full functionality, macOS may also prompt for:
- Contacts — lets SocializeAI show names instead of raw phone numbers or Apple IDs
- Automation — lets SocializeAI ask Messages.app to send an approved/live iMessage
Inside the app, use Settings → Mac access → Check access to verify:
- Messages database access
- Contacts database access
- Messages.app automation
SocializeAI expects a local WhatsApp bridge that stores messages in SQLite and exposes a loopback REST API.
Open Settings → WhatsApp → Personal bridge and click Start bridge. SocializeAI will:
- Use an existing Go runtime if one is installed.
- Otherwise download a private app-managed Go runtime into SocializeAI's app data folder.
- Clone the maintained
verygoodplugins/whatsapp-mcpbridge into SocializeAI's app data folder if needed. - Open the bridge in Terminal so you can scan the WhatsApp QR code.
On first run, scan the QR code with WhatsApp on your phone. After pairing, the bridge stores:
- REST API token:
whatsapp-bridge/store/.bridge-token - Message database:
whatsapp-bridge/store/messages.db - Default API URL:
http://127.0.0.1:8080/api
Click Check bridge or refresh WhatsApp chats after pairing. If the bridge database already exists in a common checkout path, SocializeAI auto-detects the messages.db path.
The app reads WhatsApp history locally from the bridge database and sends through /api/send. It does not copy bridge code into this repository.
SocializeAI is intentionally local-first.
- Raw iMessage history is read locally from your Mac
- Raw WhatsApp history is read locally from your WhatsApp bridge database
- API keys are stored through Electron's secure local storage path
- The app does not include analytics, telemetry, cloud accounts, or background sync
- Autopilot only runs for chats explicitly enabled by the user
- Sensitive content is blocked or held for human handling
- Screen-share mode can blur private names, numbers, messages, inputs, and logs
Use automated sending responsibly. Laws, platform rules, and personal expectations around automated messages can vary by context.
| Component | Technology |
|---|---|
| Desktop Shell | Electron |
| Frontend | React 19 + Vite |
| Language | TypeScript |
| AI Providers | OpenAI, Ollama, OpenAI-compatible local APIs |
| Local Messaging | macOS Messages database + Messages.app AppleScript |
| WhatsApp Messaging | Local whatsmeow bridge SQLite + REST API |
| Contact Resolution | Apple AddressBook local database |
| State | Local JSON state under Electron user data |
| Packaging | electron-builder |
SocializeAI/
├── docs/
│ └── ai-messaging-blueprint.md
├── electron/
│ ├── main.ts
│ └── preload.ts
├── src/
│ ├── App.tsx
│ ├── browserApi.ts
│ ├── main.tsx
│ ├── shared.ts
│ └── styles.css
├── package.json
└── vite.config.ts
npm run typecheck
npm run build
npm run package:macCurrent verification status:
- TypeScript checks: passing
- Production build: passing
- macOS app packaging: passing
- Packaged app launch: verified locally
- iMessage chat loading: verified locally with Full Disk Access
- WhatsApp bridge integration: typechecked and UI-previewed; requires a running personal bridge for live sends
MIT License © 2026 Mark Santos
Built with ❤️ by NoSleepLab