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. Each verification adds a key, named with --label (default "aitextaroo on "). If you already have an account, nothing else is signed out: your other keys, connected apps and forwarding keep working, and you get a text saying a key was added. An account holds up to 10 keys; adding an 11th removes the one unused the longest, never the one that forwards your texts (setup prints which, and you get a text about it).

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, set-pin and remove-pin read the PIN from stdin when it isn't an argument, and so do webhook set and disconnect with a bare --pin. 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 connections                                                  # keys and app sign-ins; "current" is this key
aitextaroo disconnect <connection id>                                   # remove one; 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.

An account has one stream at a time: starting a second bridge, even with another key, stops the first. A bridge also stops when its key is removed from the account. Either way it says why and exits with code 0 instead of reconnecting, so a service set to restart on failure leaves it stopped (setup guide, section C). So does a key the API rejects (wrong, or removed while the bridge was off). Set up a service before 0.3.0? Run the guide's snippet again: older service files restart the bridge even after a clean stop, so two bridges keep kicking each other off.

The bridge and listen() in 0.3.0 need the API released with them, the first that ends streams with server_restarting when it restarts (api.aitextaroo.com runs it). An older API ends every stream with evicted when it shuts down, which 0.3.0 treats as a stop.

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, set_pin, get_account, get_upgrade_link, set_webhook, remove_webhook, list_connections, remove_connection, 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

What counts toward the daily limit: texts your agent sends (to you or your contacts), your contacts' replies forwarded to you, and your > replies to them. Your own texts to your agent don't count, but once the limit is reached, texts pause both ways until it resets. A contact's replies are forwarded for an hour after your agent (or you, with >) last texted them, at most 20 an hour and 50 a day, and they stop being forwarded once 80% of the day's limit is used (you get one text saying so), so contacts can't use up the texts you need with your agent. 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.
• Security events such as PIN checks and changes are kept as just a time and a kind, only to enforce their limits, and for two days at most. Records of removed or expired app sign-ins are deleted after 30 days.
• You get a text whenever a key is added or an app signs in. On the dashboard you can see and remove connected apps and keys, stop forwarding, set or remove your PIN (removing it there always works, even if you forgot it), or sign out everything, which also signs out your other browsers. Agents can list connections and remove one too (with your PIN if you set one), and you're texted when one is removed.
• 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.3.0 && git push origin v0.3.0. The Release workflow tests, builds and publishes to PyPI with Trusted Publishing.

License

MIT