Metadata-Version: 2.5
Name: better-call-claude
Version: 0.1.0
Summary: Give Claude and other AI agents a safe way to call your phone.
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,mcp,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: mcp<3,>=2.2
Description-Content-Type: text/markdown

# Better Call Claude

Let Claude—or any MCP-compatible AI agent—call your phone with a short spoken update.

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

The guided setup saves your Twilio credentials locally, registers a `call_me` MCP tool with Claude Code, and installs a small skill that teaches Claude when a phone call is appropriate. Restart Claude Code, then try:

> Call me and say the setup worked.

## Why this shape?

This first version makes simple outbound voice alerts. There is no public webhook, tunnel, hosted service, or background daemon. Twilio receives inline TwiML and reads the agent's message aloud.

That 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.”

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

## 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)
- Claude Code, 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."

# 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
```

## Other MCP clients

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

The command prints a stdio MCP configuration for your client. The server exposes one tool:

```text
call_me(message: 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.

## 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

The Auth Token is a valuable secret. Do not commit the config file, paste it into a prompt, or share it in logs.

## 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.1.0-py3-none-any.whl better-call-claude --help`.

## Current limitation

The tool confirms that Twilio accepted and queued the call. It cannot tell whether the user answered or listened to the message. Delivery tracking and two-way conversation would require a reachable webhook service and are intentionally outside this zero-infrastructure MVP.

## License

MIT
