Send and receive iMessages via Claude Code using Sendblue

GitHub stars
92

Install

/plugin install imessage@imessage-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add njerschow/textme.

Contents

Discovered from source

Skills 1

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

Commands 2

/stoptext - Disable Text Mode

Disable "text me" mode and return to terminal-only interaction.

Usage

/stoptext

Instructions

When the user runs /stoptext:

  1. Remove the state file at ~/.config/claude-imessage/textme-enabled if it exists
  2. Confirm in terminal: "Text mode disabled. Back to terminal-only interaction."
  3. Optionally send final iMessage via notify_user: "Text mode off. Back to terminal!"

Notes

  • This is equivalent to /textme off
  • After running this, Claude will no longer automatically text the user
  • User can re-enable anytime with /textme

/textme - Enable Text Mode

Enable "text me" mode. When enabled, Claude will automatically text you via iMessage when:

  • A task is completed
  • Claude needs your input or approval
  • Claude is blocked and needs guidance

Usage

/textme        - Enable text mode
/textme on     - Enable text mode
/textme off    - Disable text mode (same as /stoptext)
/textme status - Check if text mode is enabled

Instructions

When the user runs /textme or /textme on:

  1. Create a state file at ~/.config/claude-imessage/textme-enabled with content 1
  2. Confirm: "Text mode enabled. I'll text you when I complete tasks or need input. Use /stoptext when you're back."
  3. Send an iMessage via notify_user: "Text mode enabled! I'll message you here when I'm done or need input."

When the user runs /textme off:

  1. Remove the state file ~/.config/claude-imessage/textme-enabled
  2. Confirm: "Text mode disabled. Back to terminal-only."

When the user runs /textme status:

  1. Check if ~/.config/claude-imessage/textme-enabled exists
  2. Report: "Text mode is currently [enabled/disabled]"

Behavior When Enabled

After EVERY response while text mode is enabled:

  • If you completed significant work: use notify_user to send a summary
  • If you need user input: use ask_user to ask via text and WAIT for response
  • If you're blocked: use ask_user to explain what you need

The user can respond via their phone, and you'll receive their reply through the MCP tools.

Example Flow

User: /textme
Claude: Text mode enabled. I'll text you when I complete tasks or need input.
        [Sends iMessage: "Text mode on! I'll message you here."]

User: Fix the auth bug and add tests
Claude: [Works on the bug...]
        [Sends iMessage: "Fixed auth bug + added 3 tests. Ready to push?"]
        [Waits for text response...]

User responds via phone: "yes push it"
Claude: [Receives response via MCP]
        [Pushes to remote]
        [Sends iMessage: "Pushed to main. Anything else?"]

Hooks 1

MCP servers 1

Sponsors

Details

Marketplace
njerschow/textme
Category
Community