WOPR iMessage Plugin

iMessage/SMS integration for WOPR on macOS using the imsg CLI tool.

Part of the WOPR ecosystem - Self-sovereign AI session management over P2P.

⚠️ macOS Only

This plugin only works on macOS with Messages.app configured.

Prerequisites

1. macOS with Messages.app signed in to iMessage
2. imsg CLI - Install via Homebrew:

   brew install steipete/tap/imsg

3. Full Disk Access - WOPR needs access to ~/Library/Messages/chat.db
4. Automation Permission - Grant when prompted for Messages.app control

Installation

wopr plugin install wopr-plugin-imessage

Configuration

Minimal Config

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/usr/local/bin/imsg"
    }
  }
}

Full Config

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/usr/local/bin/imsg",
      "dbPath": "/Users/<you>/Library/Messages/chat.db",
      "service": "auto",
      "region": "US",
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123", "[email protected]"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15555550123"],
      "includeAttachments": false,
      "mediaMaxMb": 16,
      "textChunkLimit": 4000
    }
  }
}

Security Policies

DM Policies

• pairing (default) - Unknown contacts must be approved
• allowlist - Only respond to configured handles
• open - Accept all DMs
• closed - Ignore all DMs

Group Policies

• allowlist (default) - Only respond in configured groups
• open - Respond in all groups
• disabled - Ignore all groups

Setup Instructions

1. Install imsg CLI:

   brew install steipete/tap/imsg

2. Grant Full Disk Access:

   • System Settings → Privacy & Security → Full Disk Access
   • Add your terminal app and WOPR process

3. Test imsg:

   imsg chats --limit 5

4. Configure WOPR:

   wopr onboard  # Or edit ~/.wopr/config.json

5. Approve Permissions:

   • First message will prompt for Automation access
   • Grant permission for WOPR to control Messages.app

Dedicated Bot User (Optional)

For a separate iMessage identity from your personal account:

1. Create a new macOS user (e.g., woprbot)
2. Sign into Messages with a dedicated Apple ID
3. Enable Remote Login (SSH)
4. Set up SSH key authentication
5. Create a wrapper script:

   #!/bin/bash
   exec ssh woprbot@localhost /usr/local/bin/imsg "$@"

6. Set cliPath to your wrapper script

Remote Mac via SSH

If WOPR runs on Linux but iMessage needs to be on a Mac, use an SSH wrapper script:

1. Create a wrapper script on your Linux host:

   #!/bin/bash
   exec ssh -T user@mac-host /usr/local/bin/imsg "$@"

2. Make it executable and point your config to it:

   {
     "channels": {
       "imessage": {
         "enabled": true,
         "cliPath": "/path/to/imsg-ssh-wrapper"
       }
     }
   }

3. Ensure SSH key authentication is set up (no password prompts)

Commands

List recent chats:

imsg chats --limit 20

Send test message:

imsg send --to "+15555550123" "Hello from WOPR"

Troubleshooting

"imsg not found"

• Install: brew install steipete/tap/imsg
• Check path: which imsg

"Failed to start imsg rpc"

• Grant Full Disk Access to your terminal/IDE
• Ensure Messages.app is signed in
• Check Console.app for permission prompts

Messages not received

• Check imsg chats works manually
• Verify DM/group policies in config
• Check WOPR logs (location depends on WOPR_HOME environment variable):
  • Error log: $WOPR_HOME/logs/imessage-plugin-error.log
  • Debug log: $WOPR_HOME/logs/imessage-plugin.log

Automation permission denied

• System Settings → Privacy & Security → Automation
• Ensure WOPR can control Messages.app

Development

npm install
npm run build
npm run watch

Architecture

The plugin communicates with the imsg CLI tool via JSON-RPC over stdio:

1. Plugin spawns imsg rpc as a child process
2. Sends JSON-RPC requests via stdin
3. Receives responses and notifications via stdout
4. Incoming messages arrive as JSON-RPC notifications (message or message.received)

Available RPC Methods

The IMessageClient class exposes these methods:

| Method | Description | Timeout | |--------|-------------|---------| | sendMessage(params) | Send a message | 60s | | listChats(limit) | List recent chats | 10s | | getChatHistory(chatId, limit) | Get chat message history | 10s |

Configuration Schema

The plugin registers a config schema for WOPR's WebUI. All fields have sensible defaults:

| Field | Type | Default | Description | |-------|------|---------|-------------| | enabled | boolean | true | Enable/disable plugin | | cliPath | string | "imsg" | Path to imsg executable | | dbPath | string | auto | Messages database path | | service | string | "auto" | auto, imessage, or sms | | region | string | "US" | SMS region code | | dmPolicy | string | "pairing" | DM handling policy | | groupPolicy | string | "allowlist" | Group handling policy | | includeAttachments | boolean | false | Include media attachments | | mediaMaxMb | number | 16 | Max attachment size in MB | | textChunkLimit | number | 4000 | Max chars per message chunk |

Session Keys

Sessions are keyed based on message context:

• DMs: imessage-dm-{sender}
• Groups: imessage-group-{chat_id}

License

MIT