# Textme

> Send and receive iMessages via Claude Code. Get real-time input from the user via their phone, similar to how call-me enables voice conversations. Use when this capability is needed.

- Skill: `tomevault-io/textme` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/textme`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/textme/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/textme

---

# iMessage Skill

## Description
Send and receive iMessages via Claude Code. Get real-time input from the user via their phone, similar to how call-me enables voice conversations.

## When to Use This Skill

**Use `ask_user` when:**
- You've **completed significant work** and want to report status and ask what's next
- You need **real-time input** for decisions
- You're **blocked** and need clarification to proceed
- You want to **discuss next steps** with the user

**Use `notify_user` when:**
- You want to send a **status update** without needing a response
- The information is **non-urgent**
- You don't want to block waiting for a reply

**Do NOT use for:**
- Simple yes/no questions that can be asked in the terminal
- Information the user has already provided
- Sending to non-whitelisted numbers

## Primary Tools

### `ask_user`
Send an iMessage and wait for the user to respond. **This is the main tool** - similar to `initiate_call` in call-me.

**Parameters:**
- `message` (string, required): What to ask the user. Be conversational.
- `timeout_seconds` (number, optional): How long to wait (default: 300 = 5 minutes)

**Behavior:**
1. Sends iMessage to the user
2. Waits for response (polls every 5 seconds)
3. Returns the user's response when received
4. If timeout: returns notice, response will be picked up later via `check_messages`

**Example:**
```
ask_user({ message: "Finished the auth module. Should I work on API endpoints or tests next?" })
→ User responds via phone: "API endpoints"
→ Returns: "User responded: API endpoints"
→ Claude continues working on API endpoints
```

### `notify_user`
Send an iMessage without waiting for a response. Fire-and-forget.

**Parameters:**
- `message` (string, required): Message to send

**Example:**
```
notify_user({ message: "Starting the database migration. This will take about 10 minutes." })
→ Returns immediately: "Notification sent"
→ Claude continues working
```

## Secondary Tools

### `check_messages`
Check for pending iMessages. Use this to pick up responses that arrived after a timeout.

### `send_message`
Send a message to a specific number. Lower-level than `notify_user`.

### `get_conversation`
Get conversation history with a contact for context.

### `mark_read`
Mark a message as processed without responding.

### `list_contacts`
List all contacts who have messaged.

### `clear_history`
Clear conversation history with a contact.

## Example Workflows

**Simple question and continue:**
```
Claude: [finishes auth module]
Claude: ask_user("Hey! Finished the auth module. API endpoints or tests next?")
        → sends iMessage, waits...
User:   [responds on phone] "API endpoints please"
Claude: → receives response
Claude: [continues with API endpoints]
```

**Status update (no response needed):**
```
Claude: notify_user("Starting the build process. Will let you know when done.")
Claude: [runs build]
Claude: ask_user("Build complete! 0 errors. Ready to deploy to staging?")
User:   "Yes, deploy it"
Claude: [deploys to staging]
```

**Multi-turn conversation:**
```
Claude: ask_user("I found 3 approaches for the caching layer. Want me to explain them?")
User:   "Yes please"
Claude: ask_user("Option 1: Redis - fast, needs server. Option 2: In-memory - simple, no persistence. Option 3: SQLite - persistent, slower. Which sounds best?")
User:   "Redis"
Claude: [implements Redis caching]
```

## Best Practices

1. **Be conversational** - Write messages like texts, not documentation
2. **Be concise** - Phone screens are small
3. **Provide context** - Explain what you did before asking
4. **Offer clear options** - "A or B?" is easier than open-ended questions
5. **Use `notify_user` for updates** - Don't block when you don't need input
6. **Trust the timeout** - If no response in 5 min, user is busy - continue or wait

## How It Works

- MCP server polls Sendblue every 5 seconds for new messages
- `ask_user` blocks up to 5 minutes waiting for response
- Only whitelisted phone numbers can send/receive
- Conversation history is maintained for context
- Stop hook evaluates if Claude should proactively message the user

---
> Source: [njerschow/textme](https://github.com/njerschow/textme) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-28 -->