Metadata-Version: 2.5
Name: better-call-claude
Version: 0.4.0
Summary: Let Claude and other AI agents call your phone and hear your spoken reply.
Project-URL: Documentation, https://github.com/ronxldwilson/better-call-claude#readme
Project-URL: Repository, https://github.com/ronxldwilson/better-call-claude
Project-URL: Issues, https://github.com/ronxldwilson/better-call-claude/issues
Author: Ronxld Wilson
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,claude,codex,mcp,opencode,phone-call,twilio
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Telephony
Requires-Python: >=3.10
Requires-Dist: json5<1,>=0.12
Requires-Dist: mcp<3,>=2.2
Requires-Dist: twilio<10,>=9.8
Description-Content-Type: text/markdown

# Better Call Claude

[![PyPI](https://img.shields.io/pypi/v/better-call-claude)](https://pypi.org/project/better-call-claude/)
[![Python](https://img.shields.io/pypi/pyversions/better-call-claude)](https://pypi.org/project/better-call-claude/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Let Claude—or any MCP-compatible AI agent—call your phone, ask a question, and hear
your spoken reply.

Better Call Claude adds two focused MCP tools to your AI agent. `call_me` delivers a
short spoken update, while `call_and_ask_user` asks one question and returns your
transcribed response to the agent. Calls run through your own Twilio account.

## Features

- One-command installation and guided configuration
- Automatic setup for Claude Code, Codex, OpenCode, Gemini CLI, Cursor, Windsurf,
  VS Code/Copilot, and Cline
- Spoken replies with no server, domain, or Cloudflare account to configure
- Compatible with other local stdio MCP clients
- No hosted Better Call Claude service or background daemon
- Credentials remain on your computer
- Fixed recipient number, message limits, cooldowns, and hourly rate limits
- Wheel and [source distribution](https://pypi.org/project/better-call-claude/#files) published on PyPI

## Quick start

```bash
uvx better-call-claude setup
```

The guided setup saves your Twilio credentials locally, registers both calling tools
with every detected supported agent, and installs a small skill wherever that agent
supports Agent Skills. Restart your agent, then try:

> Call me and say the setup worked.

Or ask for a response:

> Call me and ask whether you should deploy now. Continue based on my answer.

## How spoken replies work

For a one-way notification, Twilio receives inline TwiML and reads the agent's message
aloud. For a question, Better Call Claude starts a local callback server and a temporary
[Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/).
Twilio asks the question with `<Gather input="speech">`, then posts the transcript back
through that encrypted tunnel. The callback server verifies Twilio's signature before
accepting the response and shuts down the tunnel after the call.

Setup reuses `cloudflared` when it is already installed. Otherwise, it downloads the
official binary from Cloudflare's latest GitHub release, verifies the release SHA-256
digest, and stores it inside Better Call Claude's private configuration directory. No
Cloudflare login is required.

This makes it useful for requests like:

- “Run the migration and call me when it finishes.”
- “Call me if the production health check fails.”
- “In 20 minutes, check the build and call me with the result.”
- “Call me, ask whether I approve the deployment, and continue from my answer.”

The scheduling or monitoring still belongs to your agent. Better Call Claude handles the final phone call.

## How it works

```text
Claude or another agent
        │
        │  call_and_ask_user({ question }) over local MCP stdio
        ▼
Better Call Claude ───► temporary Cloudflare tunnel
        │                           ▲
        │ authenticated call       │ signed speech-result webhook
        ▼                           │
      Twilio ─────────────────► your configured phone
        │                           │
        └──── transcribed reply ◄───┘
```

The AI can supply only the spoken message. Your Twilio credentials and destination number are loaded by the local process and are never included in the model's tool arguments.

## What you need

- Python 3.10 or newer
- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or `pipx`
- A [Twilio account and voice-capable number](https://www.twilio.com/docs/voice/tutorials/how-to-make-outbound-phone-calls)
- Any supported agent, or another client that supports local stdio MCP servers

Twilio trial accounts can generally call only verified recipients. Calls use your Twilio account and may incur normal voice charges.

During setup you will be asked for your Twilio Account SID, Auth Token, Twilio number, and personal number. Phone numbers must use E.164 format, such as `+14155552671`. The Auth Token prompt is hidden.

### pipx alternative

```bash
pipx run better-call-claude setup
```

## Commands

```bash
# Guided configuration and agent installation
better-call-claude setup

# Validate configuration without placing a call
better-call-claude doctor

# Place a real test call
better-call-claude call "The deployment finished successfully."

# Ask one question and print the transcribed reply
better-call-claude ask "Should I deploy now?"

# Start the stdio MCP server (normally launched by your agent)
better-call-claude mcp
```

For non-interactive setup:

```bash
TWILIO_ACCOUNT_SID=AC... \
TWILIO_AUTH_TOKEN=... \
TWILIO_FROM_NUMBER=+14155550100 \
BETTER_CALL_CLAUDE_NUMBER=+14155550101 \
uvx better-call-claude setup --agent claude
```

## Supported agents

By default, `setup` detects installed agents and configures all of them. Existing
unrelated settings and MCP servers are preserved.

| Agent | Automatic MCP setup | Skill location |
| --- | --- | --- |
| Claude Code | CLI | `~/.claude/skills` |
| Codex | CLI | `~/.codex/skills` |
| OpenCode | User config | `~/.agents/skills` |
| Gemini CLI | CLI | `~/.agents/skills` |
| Cursor | `~/.cursor/mcp.json` | MCP instructions |
| Windsurf | User config | `~/.codeium/windsurf/skills` |
| VS Code / GitHub Copilot | CLI | `~/.agents/skills` |
| Cline | User config | `~/.cline/skills` |

Select one agent explicitly:

```bash
uvx better-call-claude setup --agent opencode
uvx better-call-claude setup --agent gemini
uvx better-call-claude setup --agent cursor
uvx better-call-claude setup --agent windsurf
uvx better-call-claude setup --agent vscode
uvx better-call-claude setup --agent cline
```

`--agent all` configures every supported agent detected on the computer. Configuration
files containing JSONC comments are accepted; when changed, they are normalized to JSON.

## Other MCP clients

```bash
uvx better-call-claude setup --agent generic
```

The command prints a stdio MCP configuration for your client. The server exposes two tools:

```text
call_me(message: str)
call_and_ask_user(question: str)
```

The recipient is deliberately absent from the tool input. It is fixed during setup, so an agent cannot use your Twilio account to dial arbitrary numbers.

### Claude Code and Codex explicitly

```bash
uvx better-call-claude setup --agent claude
uvx better-call-claude setup --agent codex
uvx better-call-claude setup --agent all
```

For Codex, run `codex mcp get better-call-claude` to verify the connection, then restart Codex. The Codex CLI, IDE extension, and ChatGPT desktop app share MCP configuration on the same Codex host.

## Configuration and safety

Configuration is stored at `~/.config/better-call-claude/config.json` with owner-only permissions. Set `BETTER_CALL_CLAUDE_CONFIG` to use a different path. Environment variables override saved values:

| Variable | Purpose |
| --- | --- |
| `TWILIO_ACCOUNT_SID` | Twilio Account SID |
| `TWILIO_AUTH_TOKEN` | Twilio Auth Token |
| `TWILIO_FROM_NUMBER` | Voice-capable Twilio number |
| `BETTER_CALL_CLAUDE_NUMBER` | Fixed recipient |
| `BETTER_CALL_CLAUDE_VOICE` | Twilio `<Say>` voice; default `Polly.Joanna` |
| `BETTER_CALL_CLAUDE_LANGUAGE` | Voice language; default `en-US` |
| `BETTER_CALL_CLAUDE_PREFIX` | Spoken introduction |

Built-in guardrails:

- One fixed recipient, hidden from the model except for a masked hint
- Messages capped at 600 characters
- Three calls per hour by default
- A 60-second cooldown between calls
- Skill instructions require explicit or previously granted authorization
- No automatic retry after a failed or unanswered call
- A new random callback path and temporary tunnel for every question
- Twilio signature validation on every transcript and status callback

The Auth Token is a valuable secret. Do not commit the config file, paste it into a
prompt, or share it in logs. Spoken answers are processed by Twilio speech recognition
and pass through Cloudflare's network to the local callback server. Better Call Claude
does not retain transcripts after returning them to the agent.

## Development

```bash
uv sync
uv run pytest
uv run ruff check .
uv build --no-sources
```

To point Claude Code at a local checkout:

```bash
claude mcp add --scope user --transport stdio better-call-claude-dev -- \
  uv --directory "$PWD" run better-call-claude mcp
```

The integration follows Claude Code's documented [local stdio MCP configuration](https://code.claude.com/docs/en/mcp). Twilio calls use the documented [Call resource with inline TwiML](https://www.twilio.com/docs/voice/api/call-resource).

## Publishing to PyPI

```bash
uv build --no-sources
uv publish --dry-run
UV_PUBLISH_TOKEN=pypi-your-token uv publish
```

Create an API token in your PyPI account settings and keep it out of the repository and
shell history. Test the exact wheel first with
`uvx --from dist/better_call_claude-0.4.0-py3-none-any.whl better-call-claude --help`.

## Conversation scope

`call_and_ask_user` collects one spoken answer per call. It is intentionally bounded,
rather than an open-ended realtime voice conversation. A later version can add multiple
back-and-forth turns with Twilio ConversationRelay or bidirectional Media Streams.

## License

MIT
