AI Text-a-roo

Give any AI agent a phone number, in about two minutes.

AI Text-a-roo is an SMS gateway for AI agents. You verify your phone once; then you can text your agent from any phone (no app), and it can text you back, or first, when something needs you. This repo has everything an agent needs to use it: an Agent Skill, plugin manifests for Claude, Codex, Cursor and Gemini CLI, the aitextaroo command, a Python SDK, and an SMS bridge for CLI agents.

Install in your agent

The plugins bundle the skill and the remote MCP server. They sign in with OAuth: you enter your phone number and the 6-digit code we text you, so there's no API key to copy. Setup guides for each agent: https://aitextaroo.com/agents.

Or just tell your agent:

Set me up with AI Text-a-roo so I can text you. Instructions: aitextaroo.com/llms.txt

Quick start from a terminal

pipx install aitextaroo                                      # or: pip install --user aitextaroo
aitextaroo-setup --phone +12125551234                        # texts you a 6-digit code
aitextaroo-setup --phone +12125551234 --code 123456 --save   # saves the key (owner-only)
aitextaroo send "Hello from my agent!"

--save stores the API key in ~/.aitextaroo/credentials.json with owner-only permissions. aitextaroo and aitextaroo-bridge find it there, or in AITEXTAROO_API_KEY, or in --api-key. Verifying a phone that already has an account makes a new key: apps connected before are signed out and webhook forwarding is turned off.

The aitextaroo command

Made for agents with a shell. Output is JSON; errors go to stderr with exit code 1. aitextaroo verify-pin exits 2 when the PIN is wrong, so aitextaroo verify-pin <<< 4821 && … only continues on a match. verify-pin and set-pin read the PIN from stdin when it isn't an argument. At a terminal they ask for it without echoing, which keeps it out of your shell history (a command with the PIN written in it, like the <<< form, can still be saved there).

aitextaroo send "Build finished: 318 tests passing."
aitextaroo ask "Deploy to production? Reply YES or NO" --timeout 120   # text, then wait for the answer
aitextaroo wait --timeout 60                                            # wait for the next text
aitextaroo recent                                                       # texts from the last 5 minutes
aitextaroo relay --to +12125550100 --name Mom "Happy birthday!"        # Pro: text a contact
aitextaroo verify-pin                                                   # check a PIN (hidden prompt)
aitextaroo set-pin                                                      # set the user's PIN (4-8 digits)
aitextaroo set-pin --current                                            # change it: current PIN, then the new one
aitextaroo remove-pin                                                   # needs the current PIN
aitextaroo account
aitextaroo upgrade                                                      # Stripe link for Pro
aitextaroo webhook set https://example.com/hook --auth-header "Bearer <token>"   # add --pin if a PIN is set
aitextaroo connect [claude-code|codex|gemini|cursor|muse-code|claude|chatgpt|grok]

SMS bridge

The bridge holds one outbound connection to AI Text-a-roo. Each text you send becomes a prompt for a CLI agent on your machine, and its answer is texted back. No webhook, no public IP: it works behind NAT, firewalls and VPNs.

aitextaroo-bridge                       # auto-detects an installed agent
aitextaroo-bridge --agent codex
aitextaroo-bridge --agent-command "pnpm --silent --dir ~/nanoclaw run chat"   # any other CLI

Auto-detect tries them in this order. --agent-command runs any CLI that takes the prompt as its last argument and prints the reply.

Conversation history is saved locally in ~/.aitextaroo/sessions/ and survives restarts. Text /help, /new (fresh conversation) or /status. Use --no-persist for memory-only history. Responses are stripped of markdown for SMS.

aitextaroo-bridge [OPTIONS]
  --api-key KEY          API key (default: AITEXTAROO_API_KEY or the saved credentials)
  --agent NAME           auto, claude, codex, hermes, openclaw, grok, gemini, antigravity, goose, cursor
  --agent-command CMD    Any other CLI agent (overrides --agent)
  --sessions-dir PATH    Session files (default ~/.aitextaroo/sessions/)
  --no-persist           Keep history in memory only
  --base-url URL         Custom API URL
  -v, --verbose          Debug logging

Python SDK

import asyncio
from aitextaroo import TextarooClient

async def main():
    client = TextarooClient(api_key="YOUR_KEY")
    await client.send("All tests pass. Open a PR? Reply YES or NO.")
    reply = await client.wait_for_reply(timeout_seconds=90)
    print(reply.text if reply else "No answer yet")
    await client.close()

asyncio.run(main())

InboundMessage has id, text, received_at, channel ("sms"), trust_level and has_pin. See examples/ for an echo bot, a listener and an ask-and-wait flow.

MCP server

https://api.aitextaroo.com/mcp (streamable HTTP). Tools: send_text, wait_for_reply, get_recent_messages, text_contact, verify_pin, get_account, get_upgrade_link, set_webhook, remove_webhook, and get_help (how it works and how it's secured, for answering the user's questions). Clients sign in with OAuth, or send Authorization: Bearer <API key>:

claude mcp add --transport http --scope user aitextaroo https://api.aitextaroo.com/mcp \
  --header "Authorization: Bearer $AITEXTAROO_API_KEY"

Run aitextaroo connect for every client's exact setup. Reference: https://aitextaroo.com/docs/mcp.

Plans

Up to 5 texts per minute. Limits reset at midnight UTC.

Privacy and security

• Message content is never written to AI Text-a-roo's database. Texts are held in memory for at most five minutes so an agent can catch up after a dropped connection.
• Phone numbers are encrypted at rest; PINs are stored as bcrypt hashes.
• The bridge's history and the saved credentials live only on your machine.
• SMS isn't end-to-end encrypted, and sender IDs can be spoofed. The bridge tells every agent to ask for your PIN before anything sensitive, because some CLIs (for example hermes -z) auto-approve their own tool calls in one-shot mode. Run the bridge with an agent whose permissions you're comfortable exposing to your phone number.

Details: https://aitextaroo.com/security.

Environment variables

Releasing

Bump the version in pyproject.toml, aitextaroo/__init__.py, plugin.json, .claude-plugin/plugin.json and gemini-extension.json, merge to main, then push a matching tag: git tag v0.2.2 && git push origin v0.2.2. The Release workflow tests, builds and publishes to PyPI with Trusted Publishing.

License

MIT