iMessage Notification Skill

Purpose: Send iMessage notifications to alert you when OpenCode needs your attention.

What I do

• •Send notification messages to your iPhone via iMessage
• •Alert you when OpenCode needs approval or confirmation
• •Notify you when long-running tasks complete
• •Provide context about what requires your attention
• •Support custom recipients and message templates

When I'm activated

OpenCode automatically invokes this skill when:

• •Approval gates are triggered (@approval_gate)
• •Task completion requires confirmation
• •Long-running operations finish
• •Errors require user intervention
• •You explicitly request notification via MCP tool or slash command

How to use me

Explicit invocation (via slash command):

/imessage:notify --recipient "+1234567890" --message "Task completed: Code review finished"

Explicit invocation (via MCP tool):

// Available MCP tools:
send_imessage_notification({
  recipient: "+1234567890",
  message: "Task completed successfully"
})

Automatic triggers:

The skill activates based on OpenCode's workflow stages:

• •Stage 2: Approval requests
• •Stage 4: Validation failures
• •Stage 6: Session completion confirmations

Tools Provided

Examples

Approval Request Notification

When OpenCode needs approval, sends:

🤖 OpenCode Approval Needed

Action: Execute proposed plan
Task: Review code changes
Please review and approve.

Completion Notification

When task completes, sends:

✅ Task Complete

Feature: User authentication
Status: All tests passed
Duration: 15 min

Error Alert

When errors occur, sends:

⚠️ OpenCode Error

Error: Test failures detected
Suggestion: Review test output and approve fixes

Configuration

Required Setup

1. •Install imsg CLI:

# Build from source
git clone https://github.com/steipete/imsg.git
cd imsg
make build
sudo cp ./bin/imsg /usr/local/bin/

# Or check if available via Homebrew
brew install imsg

1. •

   Grant permissions:

   • •Full Disk Access: System Settings → Privacy & Security → Full Disk Access → Add your terminal
   • •Automation Permission: System Settings → Privacy & Security → Automation → Messages → Allow terminal
2. •

   Configure recipient: Edit config/default.json and set your phone number:

{
  "defaultRecipient": "+1234567890"
}

Configuration File

{
  "defaultRecipient": "+1234567890",
  "enabled": true,
  "events": {
    "approval": true,
    "completion": true,
    "error": true,
    "confirmation": true
  },
  "templates": {
    "approval": "🤖 OpenCode Approval Needed\n\n$CONTEXT",
    "completion": "✅ Task Complete\n\n$TASK\n$DETAILS",
    "error": "⚠️ OpenCode Error\n\n$ERROR\n$SUGGESTION",
    "confirmation": "📋 OpenCode Confirmation\n\n$REQUEST"
  },
  "imsg": {
    "binaryPath": "/usr/local/bin/imsg",
    "service": "imessage",
    "region": "US"
  }
}

Installation

For Development

# Clone and enter directory
git clone https://github.com/yourusername/opencode-imessage-notifier.git
cd opencode-imessage-notifier

# Install dependencies
npm install

# Test locally
npx ts-node scripts/notify.ts notify -r "+1234567890" -m "Test notification"

# Load in OpenCode for development
claude --plugin-dir ./opencode-imessage-notifier

For Production

# Install via plugin manager (once published)
/plugin install imessage-notifier

Architecture

skills/imessage-notify/
├── SKILL.md              # This file
├── router.sh             # CLI router (optional)
└── scripts/
    └── notify.ts         # Core notification logic

mcp/
├── .mcp.json             # MCP server configuration
└── server.ts             # MCP server implementation

commands/
└── notify.md             # Slash command definition

.claude-plugin/
└── plugin.json           # Plugin manifest

Troubleshooting

"imsg not found"

Ensure imsg is installed and in your PATH:

which imsg
# Should return: /usr/local/bin/imsg

If not, install it as shown in the setup section.

"Permission denied" errors

1. •Grant Full Disk Access to your terminal
2. •Grant Automation permission for Messages.app
3. •Restart terminal after granting permissions

"Unable to open database file"

This means Full Disk Access wasn't granted properly:

1. •System Settings → Privacy & Security → Full Disk Access
2. •Add your terminal app
3. •Restart terminal
4. •Try again

Messages not being sent

Check that Messages.app is signed in and iMessage is working normally.

Integration

With OpenCode Workflow

• •Stage 2 (Approve): Sends approval request notifications
• •Stage 4 (Validate): Sends error/completion notifications
• •Stage 6 (Confirm): Sends session summary notifications

With MCP Tools

Explicit tools available globally via MCP protocol:

• •send_imessage_notification
• •send_approval_request
• •send_completion_notification
• •send_error_alert
• •send_confirmation_request

Requirements

• •macOS 14+ with Messages.app signed in
• •imsg CLI installed
• •Full Disk Access granted
• •Automation permission for Messages.app

Requires: imsg CLI installed and configured Author: Your Name Version: 1.0.0