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

### 3. Run in background (recommended)

## Configuration

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

## 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:

### Natural Language

You can also just ask naturally:

- "Show me the auto-responder status"
- "Add +15551234567 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)

## 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`:

This ensures rate limiting works correctly across restarts.

## Prompts

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

**Examples:**

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 "+15551234567" 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., `+15551234567`)

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

## Troubleshooting

### Watcher Not Responding

**Check status:**

### Common Issues

**"OPENAI_API_KEY not found"**
- Add API key to `~/.clawdbot/clawdbot.json`:

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

# 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