iResponder

Monitor iMessage/SMS conversations and auto-respond based on configurable rules, AI prompts, and rate-limiting conditions. Use when you need to automatically reply to specific contacts with AI-generated responses based on conversation context. Also use when the user asks to manage auto-responder settings, contacts, prompts, or view status/history.

Security Scan

The skill largely does what it claims (auto-respond to iMessage) but the code and runtime instructions request access to API keys and system resources that the skill metadata does not declare, and there are a few risky behaviors (shell exec usage, reading local config files, network calls) you should review before installing.

Purpose & Capability

The skill description is an iMessage auto-responder and the SKILL.md and README consistently require macOS, the imsg CLI, and an OpenAI API key; but the package metadata declares no required env vars or binaries. The included scripts also reference Anthropic API keys (in watcher-old) and assume the 'curl' binary and Node.js are available. The codebase therefore needs credentials and CLI tools that the registry metadata does not list — an incoherence that should be resolved.

Instruction Scope

Runtime instructions ask to grant Full Disk Access and to run a long-running watcher that reads/writes config and log files under ~/clawd and reads ~/.clawdbot for API keys. The watcher spawns 'imsg' and 'curl' and sends network requests to external LLM APIs. The Telegram handler executes manage.js via execSync with interpolated arguments (potential command injection risk when fed untrusted input). These actions go beyond simple local config edits and involve reading local account/state and exfiltrating content to external APIs.

Install Mechanism

There is no automated install spec (no remote downloads). The skill is distributed with local scripts and docs only, so nothing is being fetched/installed silently by the skill itself. That reduces supply-chain risk, but it also means the shipped scripts will be run directly on the host.

Credentials

The registry lists no required environment variables, yet the code looks for OPENAI_API_KEY (and watcher-old looks for ANTHROPIC_API_KEY) and reads ~/.clawdbot for API credentials. Telegram integration is present but no bot token or network credentials are declared. Requesting Full Disk Access/Message automation is proportionate to monitoring Messages.app, but undisclosed access to API keys and config files is not proportional and should be declared/justified.

Persistence & Privilege

The skill runs a background watcher, creates PID, log, and state files under ~/clawd and persists state across restarts (normal for a watcher). always: false (not force-included). It requires macOS permissions (Full Disk Access, Messages automation) which are high-privilege but consistent with the stated function — confirm you understand the implications of granting these macOS permissions.

What to consider before installing

Things to check before installing: - Source trust: the package 'homepage' is unknown. Prefer code from a trusted repo. Review the full script contents locally before running. - Declared vs actual requirements: the registry metadata lists no env vars, but the code requires an OpenAI API key (OPENAI_API_KEY) or will try to read keys from ~/.clawdbot; watcher-old also looks for an Anthropic key. Confirm which provider/key you must supply and that you are comfortable storing it in that location. - macOS permissions: the skill requires Full Disk Access and Messages automation. Granting Full Disk Access to Terminal/iTerm allows these scripts to read many local files — only proceed if you accept that access. - Network & data exfiltration: the watcher sends conversation context to external LLM APIs (api.openai.com and/or api.anthropic.com). If you have sensitive message content, do not enable this unless you accept sending it to those services. - Telegram integration & command injection risk: telegram-handler invokes shell commands via execSync with user-provided strings. If you connect a Telegram bot or allow remote users to trigger these handlers, ensure the bot is restricted to trusted chats and consider sanitizing inputs or avoiding Telegram integration entirely. - Operational safety: run in test mode first (scripts provide a test mode) and monitor logs at ~/clawd/logs/imsg-autoresponder.log. Consider running under a separate user account or on a non-primary machine to limit blast radius. Backup ~/.clawdbot and verify no unexpected keys are leaked. - Recommended actions before install: verify the imsg CLI origin (brew tap steipete/tap), audit the scripts for any additional network endpoints, and add the required environment variables explicitly to the skill metadata or your deployment notes so you know what secrets are needed and where they will be read from. If you want, I can point out the exact lines that read credentials, perform network calls, or use execSync so you can inspect them closely.

iMessage Auto-Responder

Automatically respond to iMessages/SMS from specific contacts using AI-generated replies that match your voice and conversation context.

⚠️ Requirements Checklist

Before using this skill, ensure you have:

• macOS with Messages.app signed in to iMessage
• imsg CLI installed: brew install steipete/tap/imsg
• OpenAI API key configured in Clawdbot config
• Full Disk Access granted to Terminal/iTerm
• Messages automation permission (macOS will prompt on first use)

Features

• 🤖 AI-powered responses using OpenAI GPT-4
• 📱 Contact-based prompts - different AI personality per contact
• ⏱️ Rate limiting - configurable delays between auto-responses
• 💬 Context-aware - AI sees recent conversation history
• 📊 Telegram management - slash commands + natural language
• 🔄 Background monitoring - continuous polling for new messages
• 🔧 Auto-cleanup - clears stale locks on restart (prevents stuck contacts)
• 🧪 Test mode - generate real AI responses without sending
• ⏰ Time windows - only respond during specific hours (e.g., 9 AM - 10 PM)
• 🔑 Keyword triggers - only respond if message contains specific keywords (e.g., "urgent", "help")
• 📊 Statistics tracking - track total responses, daily counts, and averages per contact
• 🚦 Daily cap - limit max replies per day per contact (safety feature)

Quick Start

1. Add contacts to watch list

cd ~/clawd/imsg-autoresponder/scripts
node manage.js add "[phone]" "Reply with a middle finger emoji" "Best Friend"
node manage.js add "[phone]" "You are my helpful assistant. Reply warmly and briefly, as if I'm responding myself. Keep it under 160 characters." "Mom"

2. Start the watcher

node watcher.js

The watcher runs in the foreground and logs to ~/clawd/logs/imsg-autoresponder.log.

3. Run in background (recommended)

# Start in background
nohup node ~/clawd/imsg-autoresponder/scripts/watcher.js > /dev/null 2>&1 &

# Or use screen/tmux
screen -S imsg-watcher
node ~/clawd/imsg-autoresponder/scripts/watcher.js
# Ctrl+A, D to detach

Configuration

Config file: ~/clawd/imsg-autoresponder.json

{
  "enabled": true,
  "defaultMinMinutesBetweenReplies": 15,
  "watchList": [
    {
      "identifier": "[phone]",
      "name": "Best Friend",
      "prompt": "Reply with a middle finger emoji",
      "minMinutesBetweenReplies": 10,
      "enabled": true
    }
  ]
}

Management via Telegram (Recommended)

The auto-responder can be managed directly through Telegram using slash commands or natural language.

Slash Commands

Both space and underscore formats are supported:

/autorespond list              OR  /autorespond_list
/autorespond status            OR  /autorespond_status
/autorespond add               OR  /autorespond_add <number> <name> <prompt>
/autorespond remove            OR  /autorespond_remove <number>
/autorespond edit              OR  /autorespond_edit <number> <prompt>
/autorespond delay             OR  /autorespond_delay <number> <minutes>
/autorespond history           OR  /autorespond_history <number>
/autorespond test              OR  /autorespond_test <number> <message>
/autorespond toggle            OR  /autorespond_toggle
/autorespond restart           OR  /autorespond_restart

Bulk Operations:
/autorespond set-all-delays    OR  /autorespond_set_all_delays <minutes>
/autorespond enable-all        OR  /autorespond_enable_all
/autorespond disable-all       OR  /autorespond_disable_all

Time Windows:
/autorespond set-time-window   OR  /autorespond_set_time_window <number> <start> <end>
/autorespond clear-time-windows OR  /autorespond_clear_time_windows <number>

Keyword Triggers:
/autorespond add-keyword       OR  /autorespond_add_keyword <number> <keyword>
/autorespond remove-keyword    OR  /autorespond_remove_keyword <number> <keyword>
/autorespond clear-keywords    OR  /autorespond_clear_keywords <number>

Statistics & Limits:
/autorespond stats             OR  /autorespond_stats [<number>]
/autorespond set-daily-cap     OR  /autorespond_set_daily_cap <number> <max>

Examples:

/autorespond_list
/autorespond_status
/autorespond_edit [phone] Be more sarcastic
/autorespond_delay [phone]
/autorespond_history [phone]
/autorespond_set_time_window [phone]:00 22:00
/autorespond_clear_time_windows [phone]
/autorespond_add_keyword [phone] urgent
/autorespond_add_keyword [phone] help
/autorespond_clear_keywords [phone]
/autorespond_stats
/autorespond_stats [phone]
/autorespond_set_daily_cap [phone]
/autorespond_set_all_delays 30
/autorespond_disable_all
/autorespond_restart

Natural Language

You can also just ask naturally:

• "Show me the auto-responder status"
• "Add [phone] to the watch list with prompt: be sarcastic"
• "Change Scott's prompt to be nicer"
• "Disable auto-replies for Mom"
• "What has the auto-responder sent to Foxy recently?"
• "Restart the auto-responder"

The agent will understand and execute the command using the telegram-handler.js script.

Command-Line Management (Advanced)

cd ~/clawd/imsg-autoresponder/scripts

# List all contacts
node manage.js list

# Add contact
node manage.js add "[phone]" "Your custom prompt here" "Optional Name"

# Remove contact
node manage.js remove "[phone]"

# Enable/disable contact
node manage.js enable "[phone]"
node manage.js disable "[phone]"

# Set custom delay for contact (in minutes)
node manage.js set-delay "[phone]" 30

# Toggle entire system on/off
node manage.js toggle

How It Works

1. Watcher monitors all incoming messages via imsg watch
2. Checks watch list to see if sender is configured for auto-response
3. Rate limiting ensures we don't spam (configurable minutes between replies)
4. Fetches message history for the conversation (last 20 messages)
5. Generates AI response using Clawdbot + the contact's configured prompt
6. Sends reply via imsg send
7. Logs everything to ~/clawd/logs/imsg-autoresponder.log

State Tracking

Response times are tracked in ~/clawd/data/imsg-autoresponder-state.json:

{
  "lastResponses": {
    "[phone]": 1706453280000
  }
}

This ensures rate limiting works correctly across restarts.

Prompts

Prompts define how the AI should respond to each contact. Be specific!

Examples:

"Reply with a middle finger emoji"

"You are my helpful assistant. Reply warmly and briefly, as if I'm responding myself. Keep it under 160 characters."

"You are my sarcastic friend. Reply with witty, slightly snarky responses. Keep it short."

"Politely decline any requests and say I'm busy. Be brief but friendly."

The AI will see:

• The contact's custom prompt
• Recent message history (last 5 messages)
• The latest incoming message

Requirements

• macOS with Messages.app signed in
• imsg CLI installed (brew install steipete/tap/imsg)
• Full Disk Access for Terminal
• Clawdbot installed and configured
• Anthropic API key (configured in ~/.clawdbot/clawdbot.json or ANTHROPIC_API_KEY env var)
• curl (pre-installed on macOS)

Safety

• Rate limiting prevents spam (default: 15 minutes between replies per contact)
• Manual override via enabled: false in config or node manage.js disable <number>
• System toggle to disable all auto-responses: node manage.js toggle
• Logs track all activity for review

Troubleshooting

Watcher not responding:

• Check ~/clawd/logs/imsg-autoresponder.log for errors
• Verify imsg watch works manually: imsg watch --json
• Ensure contact is in watch list: node manage.js list

Rate limited too aggressively:

• Adjust delay: node manage.js set-delay "[phone]" 5
• Or edit defaultMinMinutesBetweenReplies in config

AI responses are off:

• Refine the prompt for that contact
• Check message history is being captured correctly (see logs)

Agent Command Handling

When the user uses slash commands or natural language about the auto-responder, use the telegram-handler.js script.

Command Mapping (Both Formats Supported)

User Input	Normalize To	Handler Call
/autorespond list or /autorespond_list	list	node telegram-handler.js list
/autorespond status or /autorespond_status	status	node telegram-handler.js status
/autorespond add or /autorespond_add <args>	add	node telegram-handler.js add <number> <name> <prompt>
/autorespond remove or /autorespond_remove <num>	remove	node telegram-handler.js remove <number>
/autorespond edit or /autorespond_edit <args>	edit	node telegram-handler.js edit <number> <prompt>
/autorespond delay or /autorespond_delay <args>	delay	node telegram-handler.js delay <number> <minutes>
/autorespond history or /autorespond_history <num>	history	node telegram-handler.js history <number> [limit]
/autorespond test or /autorespond_test <num> <msg>	test	node telegram-handler.js test <number> <message>
/autorespond toggle or /autorespond_toggle	toggle	node telegram-handler.js toggle
/autorespond restart or /autorespond_restart	restart	node telegram-handler.js restart
/autorespond set-all-delays or /autorespond_set_all_delays <min>	set-all-delays	node telegram-handler.js set-all-delays <minutes>
/autorespond enable-all or /autorespond_enable_all	enable-all	node telegram-handler.js enable-all
/autorespond disable-all or /autorespond_disable_all	disable-all	node telegram-handler.js disable-all
/autorespond set-time-window or /autorespond_set_time_window <num> <s> <e>	set-time-window	node telegram-handler.js set-time-window <number> <start> <end>
/autorespond clear-time-windows or /autorespond_clear_time_windows <num>	clear-time-windows	node telegram-handler.js clear-time-windows <number>
/autorespond add-keyword or /autorespond_add_keyword <num> <word>	add-keyword	node telegram-handler.js add-keyword <number> <keyword>
/autorespond remove-keyword or /autorespond_remove_keyword <num> <word>	remove-keyword	node telegram-handler.js remove-keyword <number> <keyword>
/autorespond clear-keywords or /autorespond_clear_keywords <num>	clear-keywords	node telegram-handler.js clear-keywords <number>
/autorespond stats or /autorespond_stats [<num>]	stats	node telegram-handler.js stats [<number>]
/autorespond set-daily-cap or /autorespond_set_daily_cap <num> <max>	set-daily-cap	node telegram-handler.js set-daily-cap <number> <max>

Processing steps:

1. Detect /autorespond or /autorespond_ prefix
2. Extract subcommand (normalize underscores to spaces)
3. Parse remaining arguments
4. Call telegram-handler.js with appropriate parameters

Natural Language Pattern Matching

• "show/list/view auto-responder" → node telegram-handler.js list
• "add [contact] to auto-responder" → node telegram-handler.js add <number> <name> <prompt>
• "change/edit/update [contact]'s prompt" → node telegram-handler.js edit <number> <prompt>
• "set delay for [contact]" → node telegram-handler.js delay <number> <minutes>
• "disable/remove [contact] from auto-responder" → node telegram-handler.js remove <number>
• "auto-responder status" → node telegram-handler.js status
• "what has auto-responder sent to [contact]" → node telegram-handler.js history <number>
• "restart auto-responder" → node telegram-handler.js restart
• "enable/disable auto-responder" → node telegram-handler.js toggle

Contact resolution:

• When user refers to contact names, look up their phone number from the config
• Always use the full E.164 format (e.g., [phone])

After config changes: Always remind the user to restart the watcher if the command output mentions it.

Troubleshooting

Watcher Not Responding

Check status:

/autorespond_status

View logs:

tail -f ~/clawd/logs/imsg-autoresponder.log

Restart:

/autorespond_restart

Common Issues

"OPENAI_API_KEY not found"

• Add API key to ~/.clawdbot/clawdbot.json:

  {
    "skills": {
      "openai-whisper-api": {
        "apiKey": "sk-proj-YOUR_KEY_HERE"
      }
    }
  }
  

• Restart watcher after adding key

Permission errors

• Grant Full Disk Access to Terminal in System Settings
• Restart Terminal after granting access
• Verify imsg chats --json works manually

Messages not detected

• Check Messages.app is signed in
• Verify contact is in watch list: /autorespond_list
• Ensure watcher is running: /autorespond_status

Duplicate responses

• Fixed in current version via processing locks
• Restart watcher to apply fix: /autorespond_restart

Testing

Generate actual AI responses without sending (preview mode):

/autorespond_test [phone] Hey what's up?

This will:

• Use the contact's actual prompt
• Generate a real AI response via OpenAI
• Show exactly what would be sent
• NOT actually send the message

Perfect for testing new prompts before going live!

Privacy & Safety

⚠️ Important: This tool sends messages on your behalf automatically.

• Only add contacts who know they're texting an AI or won't mind
• Review responses regularly via /autorespond_history
• Use rate limiting to avoid spam
• Be transparent when appropriate
• Disable instantly if needed: /autorespond_toggle

Future Enhancements

• Smart rate limiting based on conversation patterns
• Group chat support
• Web dashboard
• Voice message transcription