textme

# TextMe ## Overview [`njerschow/textme`](https://github.com/njerschow/textme) is a local daemon that bridges inbound iMessages (via [Sendblue](https://sendblue.com)) to a Claude Code session on the user's machine. Whitelisted phone numbers can text, send voice notes, send images, and drive Claude through filesystem operations, code execution, and `cd`-based directory navigation — turning the user's phone into a remote control for Claude on their laptop. This is the **inbound** counterpart to outbound notification patterns ([[sendblue-notify]]): textme is phone → Claude; sendblue-notify is Claude → phone. ## When to Use This Skill - Use when the user says "text Claude", "text my laptop", "drive Claude from my phone", "I want to send iMessages to Claude", or "let me code from my phone". - Use when the user is heads-down away from their desk and wants to kick off, supervise, or interrupt a Claude session via SMS/iMessage. - Use when setting up a long-running headless workstation that the user wants to remote-control while travelling or away from the keyboard. - Pair with [[sendblue-notify]] for bidirectional flow — outbound completion pings + inbound commands on the same Sendblue account. - Do **not** use for outbound-only "text me when X finishes" patterns. That is [[sendblue-notify]] and does not need a daemon. ## Prerequisites - macOS or Linux host that stays online (the daemon polls Sendblue continuously). - Node.js 18+. - An active Sendblue account with API credentials and a provisioned iMessage number — set up via [[sendblue-cli]] (`sendblue setup`, then `sendblue show-keys` to surface API key/secret). - Claude Code installed and authenticated on the host (`npm install -g @anthropic-ai/claude-code`). - Optional: an OpenAI API key for Whisper voice-note transcription. ## How It Works ### Step 1: Install the daemon ```bash git clone https://github.com/njerschow/textme.git cd textme/daemon npm install npm run build mkdir -p ~/.config/claude-imessage ``` ### Step 2: Configure credentials and the whitelist Create `~/.config/claude-imessage/config.json`: ```json { "sendblue": { "apiKey": "YOUR_SENDBLUE_API_KEY", "apiSecret": "YOUR_SENDBLUE_API_SECRET", "phoneNumber": "+1SENDBLUE_NUMBER" }, "whitelist": ["+1YOUR_PHONE"], "pollIntervalMs": 5000, "conversationWindowSize": 20 } ``` The `whitelist` is the **only** authorization gate between an inbound iMessage and code execution on the host. Treat it as a security boundary, not a UX preference. Add only phone numbers the user controls; never add a shared, work, or family number "just in case". For voice transcription, optionally add to `.env` in the daemon directory: ```bash OPENAI_API_KEY=sk-... ``` ### Step 3: Run the daemon For a quick test run: ```bash cd textme/daemon npm start ``` For persistent operation (recommended once the user has verified behavior): ```bash pm2 start dist/index.js --name textme pm2 save pm2 startup ``` Or, on macOS, install the launchd service: ```bash ./scripts/install-launchd.sh ``` ### Step 4: Drive Claude from iMessage Once the daemon is running, an iMessage from a whitelisted number to the Sendblue phone number reaches Claude. Built-in commands: | Command | Effect | |---|---| | `?` | List available commands | | `status` | Show current daemon status and working directory | | `queue` | Show messages queued for processing | | `history` | Recent message history | | `home` | `cd` back to home directory | | `reset` | Return home and clear conversation history | | `cd /path` | Change working directory | | `stop` | Cancel the current Claude task | | `yes` / `no` | Approve or reject the pending action | Anything else is treated as a Claude prompt and routed to the active session. ### Step 5: Verify before relying on it Before using textme in unattended workflows, the user must: 1. Send `status` from the whitelisted phone — should get a directory + state reply. 2. Send a benign command (`pwd`, `ls`) and confirm output arrives. 3. Send something from a **non-whitelisted** number and confirm it is **ignored**, not echoed. 4. Pull the plug: kill the daemon and confirm messages stop being processed (no zombie process). If any of these fail, do not enable launchd / pm2 auto-start. ## Examples ### Example 1: Initial setup walk-through ```bash # 1. Make sure sendblue CLI is set up and creds work sendblue whoami # 2. Grab Sendblue API key & secret (these are NOT the CLI's bearer token) sendblue show-keys # 3. Clone + build the daemon git clone https://github.com/njerschow/textme.git cd textme/daemon && npm install && npm run build # 4. Fill in ~/.config/claude-imessage/config.json with the values from step 2 # and YOUR personal phone number as the only whitelist entry # 5. Start, send "?" from your phone, confirm response npm start ``` ### Example 2: Composing with `sendblue-notify` Wire outbound completion pings via [[sendblue-notify]] *and* inbound control via textme — they share the same Sendblue account but solve opposite problems: - Claude finishes a long task → texts user via [[sendblue-notify]] (`Stop` hook). - User replies "look at the diff" → textme routes that into Claude → Claude responds back via Sendblue. ### Example 3: Tail the daemon log ```bash # pm2 pm2 logs textme # Standalone tail -f ~/.local/log/claude-imessage.log ``` ### Example 4: MCP-only alternative (no daemon) If the user wants Sendblue messaging available to Claude Code as tools but does **not** want a polling daemon listening for inbound commands, they can register Sendblue as an MCP server instead: ```bash claude mcp add sendblue_api \ --env SENDBLUE_API_API_KEY=your-api-key \ --env SENDBLUE_API_API_SECRET=your-api-secret \ -- npx -y sendblue-api-mcp --client=claude-code --tools=all ``` This gives Claude outbound Sendblue tools inside a session but does **not** open the inbound phone-controls-Claude channel that textme provides. Pick textme when "text Claude from anywhere" is the goal; pick MCP when Claude only needs to send. ## Best Practices - ✅ **Whitelist exactly one phone number to start.** The whitelist is the security boundary; expand it slowly and only to numbers the user controls. - ✅ **Run the daemon as a regular user**, never as root or via `sudo`. - ✅ **Start in a sandbox directory** for first tests (`cd ~/textme-sandbox`), not in `~` or a real repo. - ✅ **Verify the non-whitelist ignore path** before enabling auto-start. A daemon that processes any sender is an open shell on the host. - ✅ **Keep `pollIntervalMs` ≥ 5000** unless the user understands the Sendblue rate limits and cost implications. - ❌ **Don't share the Sendblue number publicly.** Even with a whitelist, the host is doing per-message work; a flood from an unknown sender still costs polling cycles. - ❌ **Don't store `config.json` in a repo, dotfiles backup, or cloud sync** — it contains API credentials and the user's phone number. - ❌ **Don't run the daemon on a shared machine** without considering what every other user of that machine can now reach by sending an SMS. ## Limitations - **Outbound-only flows do not need this skill.** For "text me when X finishes" use [[sendblue-notify]]; running a daemon is overkill. - **Voice transcription requires a separate OpenAI API key.** Without it, voice notes are dropped or surfaced as un-transcribed audio depending on daemon version. - **The daemon polls on an interval** — there is no push delivery. Expect single-digit-second latency between message receipt and Claude response. - **One conversation, one machine.** This is a per-host daemon, not a multi-tenant service. Two daemons sharing one Sendblue number will both try to handle every inbound message. - **Sendblue free-plan verification still applies.** The user's phone must have texted the Sendblue number once before outbound responses from Claude reach the user (see [[sendblue-cli]] limitations). ## Security & Safety Notes textme is a **remote code execution surface gated only by a phone-number whitelist**. Treat it accordingly. - **Whitelist is the security boundary.** Anyone who can spoof or hijack a whitelisted number can drive Claude on the host. Be deliberate about which numbers go on the list and remove them when they no longer need access. <!-- security-allowlist: documented remote-control daemon; required disclosure per quality-bar.md --> - **Sendblue API credentials are sensitive.** `config.json` contains an API key, API secret, and the user's phone number. Mode it `600`, keep it out of dotfile repos, and never paste it into shared logs, gists, or screenshots. - **The daemon inherits the user's privileges.** It can read, write, and execute anything the running user can. Do not run as root, do not run from a directory with secrets the user does not want exposed to inbound SMS, and prefer a dedicated host or VM if available. - **Claude Code's permission model still applies inside the daemon-driven session** — destructive actions still surface confirmation prompts. textme exposes the `yes`/`no` reply path for those prompts, which means the *phone number* is making the approval. Make sure the whitelist matches the trust level of approving destructive operations remotely. - **Inbound messages are untrusted input.** Treat textme prompts as user input from the open internet (with phone-number authentication). Do not pipe their contents into `eval`, shell substitution, or scripts that bypass Claude Code's review. - **Lock-screen previews of replies leak.** When Claude responds to a message, the reply lands on the user's lock screen unredacted. Don't ask Claude over textme to surface secrets, tokens, or customer data via SMS — link to a local log or PR instead. - **Daemon liveness is a footgun.** If pm2/launchd is auto-restarting the daemon, the user must remember to stop it before changing whitelist entries, rotating credentials, or rebooting into an untrusted state. ## Common Pitfalls - **Whitelist drift.** A number added "for a demo" never gets removed. Audit `whitelist` whenever the host changes hands or scope. - **`apiKey` / `apiSecret` confusion.** Sendblue's API credentials (from `sendblue show-keys`) are distinct from the CLI's local bearer token in `~/.sendblue/credentials.json`. textme needs the *API* credentials, not the CLI auth file. - **Free-plan silent send failures.** If the user's phone never texted the Sendblue number first, outbound replies from Claude silently fail. Verify with `sendblue contacts` before relying on the loop. - **Auto-start before verification.** Installing the launchd plist or `pm2 save`-ing the daemon before testing the non-whitelist ignore path will baseline a potentially open daemon at boot. Verify first, persist second. - **Running the daemon in `~` or a repo with secrets.** The working directory at startup is exposed to anything textme is told to do (`ls`, `cat`, etc.). Start in a sandbox directory and `cd` deliberately. - **Confusing textme with the Sendblue MCP.** They look similar but the MCP variant only gives Claude *outbound* Sendblue tools — it does not open an inbound channel. If the user wants "text Claude from my phone", they need textme; if they want "Claude can send a text mid-session", the MCP is lighter. ## Related Skills - `@sendblue-notify` — Outbound counterpart (Claude → phone). Composes with textme to make the loop bidirectional. - `@sendblue-cli` — Account setup, credential management, and the `show-keys` command that surfaces the API key/secret textme needs. - `@sendblue-api` — HTTP API reference for users who want to build a custom inbound handler instead of using textme's daemon. - `@update-config` — If wiring textme alongside Claude Code hooks (e.g. a `Stop` hook that pings the user), use this for the settings.json edits. ## Links - Repository: <https://github.com/njerschow/textme> - License: <https://github.com/njerschow/textme/blob/main/LICENSE> (MIT) - Sendblue: <https://sendblue.com> - Sendblue docs: <https://docs.sendblue.com>