better-call-claude

# Better Call Claude

<p align="center">
  <img src="assets/marketing/hero-poster.png" alt="Better Call Claude - Agentic AI Communication Solution" width="400">
</p>

<p align="center">
  <strong>Bi-directional communication for Claude Code via Voice Calls, SMS, and WhatsApp.</strong><br>
  Call Claude from your phone to start tasks, and receive callbacks when Claude needs input or wants to share status.
</p>

> 📞 "Hey Claude, refactor the auth module and call me when you're done or need a decision."
>
> *[20 minutes later, phone rings]*
>
> 🤖 "I've finished the refactor but found a security issue. Should I fix it now or create a ticket?"

> 💬 *Or via SMS/WhatsApp:*
>
> You: "Claude, how's the deployment going?"
>
> Claude: "Deployment complete. 3 services updated, all health checks passing."

## Features

- **📱 Inbound calls** - Call Claude Code from your phone to start tasks
- **📲 Outbound calls** - Claude calls you when done, stuck, or needs decisions
- **💬 SMS messaging** - Send and receive text messages with Claude
- **📱 WhatsApp** - Full WhatsApp Business integration
- **🔄 Cross-channel context** - Start on voice, continue on WhatsApp seamlessly
- **🔗 Persistent sessions** - Claude stays alive listening for WhatsApp messages
- **🔒 Secure transport** - Tailscale Funnel with guided auto-setup
- **🗣️ Natural conversations** - Multi-turn interactions across all channels
- **🔧 Tool composable** - Claude can use other tools while communicating
- **⚡ Auto-webhook updates** - Twilio webhooks auto-update when URL changes
- **🆓 Free WhatsApp via Baileys** - Personal WhatsApp with zero API costs, no business verification
- **⌚ Works anywhere** - Phone, smartwatch, or any device

> ### ⚠️ Testing Status
>
> | Channel | Provider | Status |
> |---------|----------|--------|
> | Voice | Twilio | ✅ **Tested & Working** |
> | WhatsApp | Twilio Sandbox | ✅ **Tested & Working** |
> | SMS | Twilio | ⏳ Pending A2P 10DLC verification |
> | Voice | Telnyx | 🔬 Not yet tested |
> | SMS | Telnyx | 🔬 Not yet tested |
> | WhatsApp | Telnyx | 🔬 Not yet tested |
> | WhatsApp | Baileys (free) | 🔬 New - testing welcome |
>
> *Contributions welcome for testing other provider/channel combinations!*

---

## Quick Start

### 1. Choose Your Setup

| Setup | What You Get | Cost | Accounts Needed |
|-------|-------------|------|-----------------|
| **Baileys only** | WhatsApp messaging | **Free** | None |
| **Twilio/Telnyx** | Voice + SMS + WhatsApp | ~$1/mo + usage | Twilio/Telnyx + OpenAI |
| **Hybrid** | Voice + SMS (Twilio) + WhatsApp (Baileys) | ~$1/mo + voice usage | Twilio/Telnyx + OpenAI |

> **Just want WhatsApp?** Skip to [Option C: Baileys](#option-c-baileys-free-whatsapp) — no accounts, no API keys, completely free.

### 2. Set Up Phone Provider

<details>
<summary><b>Option A: Telnyx (Recommended - 50% cheaper)</b></summary>

1. Create account at [portal.telnyx.com](https://portal.telnyx.com) and verify identity
2. [Buy a phone number](https://portal.telnyx.com/#/numbers/buy-numbers) (~$1/month)
3. [Create a Voice API application](https://portal.telnyx.com/#/call-control/applications):
   - Set webhook URL to your tunnel URL + `/webhook/telnyx/inbound`
   - Set API version to v2
4. **Enable SMS** on your phone number:
   - Go to [Messaging](https://portal.telnyx.com/#/messaging) and create a Messaging Profile
   - Assign your phone number to the profile
   - Set SMS webhook URL to your tunnel URL + `/webhook/telnyx/sms`
5. **Enable WhatsApp** (optional):
   - Go to [WhatsApp](https://portal.telnyx.com/#/whatsapp) in portal
   - Complete WhatsApp Business verification
   - Set webhook URL to your tunnel URL + `/webhook/telnyx/whatsapp`
6. [Verify your phone number](https://portal.telnyx.com/#/numbers/verified-numbers) for outbound calls
7. Get your **Connection ID** (or Messaging Profile ID) and **API Key**

</details>

<details>
<summary><b>Option B: Twilio</b></summary>

1. Create account at [twilio.com/console](https://www.twilio.com/console)
2. [Buy a phone number](https://www.twilio.com/console/phone-numbers/incoming)
3. Configure webhooks for your number:
   - Voice webhook: your tunnel URL + `/webhook/twilio/inbound`
   - SMS webhook: your tunnel URL + `/webhook/twilio/sms`
4. **Enable WhatsApp** (optional):
   - Go to [WhatsApp Senders](https://www.twilio.com/console/sms/whatsapp/senders)
   - Complete WhatsApp Business setup
   - Set webhook URL to your tunnel URL + `/webhook/twilio/whatsapp`
5. Get your **Account SID** and **Auth Token**

</details>

<details>
<summary><b>Option C: Baileys (Free WhatsApp — no API provider needed)</b></summary>

Baileys connects directly to WhatsApp's Web protocol via WebSocket. It uses your personal WhatsApp account — no business verification, no API costs, no Twilio/Telnyx required.

**How it works:** Same as WhatsApp Web — you link a device by scanning a QR code.

**Step 1: Clone and install**

```bash
git clone https://github.com/sns45/better-call-claude
cd better-call-claude
bun install
```

**Step 2: Pair your WhatsApp**

```bash
bun run baileys:pair
```

1. A QR code will appear in your terminal
2. Open WhatsApp on your phone > **Settings > Linked Devices > Link a Device**
3. Scan the QR code
4. Wait for "Paired successfully!" message

Your session is saved in `data/baileys-auth/` — you won't need to scan again.

**Step 3: Add to Claude Code** (`~/.claude.json` or `~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "better-call-claude": {
      "command": "bun",
      "args": ["run", "/path/to/better-call-claude/src/index.ts"],
      "env": {
        "BETTERCALLCLAUDE_WHATSAPP_PROVIDER": "baileys",
        "BETTERCALLCLAUDE_USER_PHONE_NUMBER": "+1234567890"
      }
    }
  }
}
```

That's it! No Tailscale, no Twilio, no OpenAI keys needed.

**Step 4: Restart Claude Code and test**

Send a WhatsApp message to yourself (or have someone message you) — Baileys receives it and spawns a Claude task. Or ask Claude to send you a WhatsApp:

> "Send me a WhatsApp saying hello"

</details>

<details>
<summary><b>Option D: Hybrid (Twilio/Telnyx voice + Baileys WhatsApp)</b></summary>

Get the best of both worlds: Twilio/Telnyx handles voice calls and SMS, Baileys handles WhatsApp for free.

1. Set up Twilio or Telnyx (Options A/B above)
2. Run `bun run baileys:pair` to pair your WhatsApp
3. Add to your MCP config:

```json
{
  "env": {
    "BETTERCALLCLAUDE_PHONE_PROVIDER": "twilio",
    "BETTERCALLCLAUDE_WHATSAPP_PROVIDER": "baileys",
    "BETTERCALLCLAUDE_PHONE_ACCOUNT_SID": "your-account-sid",
    "BETTERCALLCLAUDE_PHONE_AUTH_TOKEN": "your-auth-token",
    "BETTERCALLCLAUDE_PHONE_NUMBER": "+15551234567",
    "BETTERCALLCLAUDE_USER_PHONE_NUMBER": "+15559876543",
    "BETTERCALLCLAUDE_OPENAI_API_KEY": "sk-..."
  }
}
```

Voice calls and SMS go through Twilio. WhatsApp goes through Baileys (free).

</details>

### 3. Set Up Tailscale Funnel (for webhooks)

> **Skip this step** if you're using Baileys-only mode (Option C). Baileys doesn't need webhooks.

Tailscale Funnel provides free, stable public URLs for receiving webhooks from your phone provider.

> **Why Tailscale?** Free unlimited tunnels, stable URLs (no random subdomains), enterprise-grade security.
>
> **Path:** Better Call Claude uses `/bcc` path (e.g., `https://your-hostname.ts.net/bcc`) to avoid conflicts with other services.

**First-time setup (automated):**

When you first start the MCP server, it will guide you through setup:

1. **Install Tailscale** (if not installed):
   ```bash
   # macOS
   brew install tailscale

   # Linux
   curl -fsSL https://tailscale.com/install.sh | sh
   ```

2. **Authenticate** - The server will auto-run `tailscale up` and open your browser

3. **Enable Funnel** - Visit the URL shown in the terminal to enable Funnel on your tailnet (one-time admin step)

That's it! The server handles the rest automatically.

### 4. Install Better Call Claude

```bash
# Quick start with bunx (recommended)
bunx better-call-claude

# Or install globally
bun install -g better-call-claude
better-call-claude
```

### 5. Add to Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "better-call-claude": {
      "command": "bunx",
      "args": ["better-call-claude"],
      "env": {
        "BETTERCALLCLAUDE_PHONE_PROVIDER": "telnyx",
        "BETTERCALLCLAUDE_PHONE_ACCOUNT_SID": "your-connection-id",
        "BETTERCALLCLAUDE_PHONE_AUTH_TOKEN": "your-api-key",
        "BETTERCALLCLAUDE_PHONE_NUMBER": "+15551234567",
        "BETTERCALLCLAUDE_USER_PHONE_NUMBER": "+15559876543",
        "BETTERCALLCLAUDE_OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

> **Note:** Tailscale setup is automatic on first run. The server will guide you through installation and authentication if needed.

Restart Claude Code. Done!

---

## Environment Variables

### Required Variables

| Variable | Description |
|----------|-------------|
| `BETTERCALLCLAUDE_PHONE_PROVIDER` | `telnyx` or `twilio` |
| `BETTERCALLCLAUDE_PHONE_ACCOUNT_SID` | Provider account/connection ID |
| `BETTERCALLCLAUDE_PHONE_AUTH_TOKEN` | Provider API key/auth token |
| `BETTERCALLCLAUDE_PHONE_NUMBER` | Your Telnyx/Twilio phone number (E.164) |
| `BETTERCALLCLAUDE_WHATSAPP_NUMBER` | WhatsApp number if different (e.g., Twilio Sandbox) |
| `BETTERCALLCLAUDE_USER_PHONE_NUMBER` | Your personal phone number |
| `BETTERCALLCLAUDE_OPENAI_API_KEY` | OpenAI API key for TTS/STT |

### Baileys (Free WhatsApp)

| Variable | Default | Description |
|----------|---------|-------------|
| `BETTERCALLCLAUDE_WHATSAPP_PROVIDER` | *(unset)* | Set to `baileys` to enable free WhatsApp |
| `BETTERCALLCLAUDE_BAILEYS_AUTH_DIR` | `data/baileys-auth` | Session credential directory |

> **Baileys-only mode:** When `WHATSAPP_PROVIDER=baileys` and no Twilio/Telnyx credentials are set, only `USER_PHONE_NUMBER` is required. No Tailscale, no OpenAI key needed.

### Tailscale (Optional)

| Variable | Default | Description |
|----------|---------|----