Voice interface for Claude Code via SIP/3CX. Call your AI, and your AI can call you.
Claude Phone gives your Claude Code installation a phone number. You can:
- Inbound: Call an extension and talk to Claude - run commands, check status, ask questions
- Outbound: Your server can call YOU with alerts, then have a conversation about what to do
| Requirement | Where to Get It | Notes |
|---|---|---|
| 3CX Cloud Account | 3cx.com | Free tier works |
| ElevenLabs API Key | elevenlabs.io | For text-to-speech |
| OpenAI API Key | platform.openai.com | For Whisper speech-to-text |
| Claude Code CLI | claude.ai/code | Requires Claude Max subscription |
| Platform | Status |
|---|---|
| macOS | Fully supported |
| Linux | Fully supported (including Raspberry Pi) |
| Windows | Not supported (may work with WSL) |
curl -sSL https://raw.githubusercontent.com/theNetworkChuck/claude-phone/main/install.sh | bashThe installer will:
- Check for Node.js 18+, Docker, and git (offers to install if missing)
- Clone the repository to
~/.claude-phone-cli - Install dependencies
- Create the
claude-phonecommand
claude-phone setupThe setup wizard asks what you're installing:
| Type | Use Case | What It Configures |
|---|---|---|
| Voice Server | Pi or dedicated voice box | Docker containers, connects to remote API server |
| API Server | Mac/Linux with Claude Code | Just the Claude API wrapper |
| Both | All-in-one single machine | Everything on one box |
claude-phone startBest for: Mac or Linux server that's always on and has Claude Code installed.
┌─────────────────────────────────────────────────────────────┐
│ Your Phone │
│ │ │
│ ↓ Call extension 9000 │
│ ┌─────────────┐ │
│ │ 3CX │ ← Cloud PBX │
│ └──────┬──────┘ │
│ │ │
│ ↓ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Single Server (Mac/Linux) │ │
│ │ ┌───────────┐ ┌───────────────────┐ │ │
│ │ │ voice-app │ ←→ │ claude-api-server │ │ │
│ │ │ (Docker) │ │ (Claude Code CLI) │ │ │
│ │ └───────────┘ └───────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Setup:
claude-phone setup # Select "Both"
claude-phone start # Launches Docker + API serverBest for: Dedicated Pi for voice services, Claude running on your main machine.
┌─────────────────────────────────────────────────────────────┐
│ Your Phone │
│ │ │
│ ↓ Call extension 9000 │
│ ┌─────────────┐ │
│ │ 3CX │ ← Cloud PBX │
│ └──────┬──────┘ │
│ │ │
│ ↓ │
│ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Raspberry Pi │ ←→ │ Mac/Linux with │ │
│ │ (voice-app) │ HTTP │ Claude Code CLI │ │
│ └─────────────┘ │ (claude-api-server) │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
On your Pi (Voice Server):
claude-phone setup # Select "Voice Server", enter API server IP when prompted
claude-phone start # Launches Docker containersOn your Mac/Linux (API Server):
claude-phone api-server # Starts Claude API wrapper on port 3333Note: On the API server machine, you don't need to run claude-phone setup first - the api-server command works standalone.
| Command | Description |
|---|---|
claude-phone setup |
Interactive configuration wizard |
claude-phone start |
Start services based on installation type |
claude-phone stop |
Stop all services |
claude-phone status |
Show service status |
claude-phone doctor |
Health check for dependencies and services |
claude-phone api-server [--port N] |
Start API server standalone (default: 3333) |
claude-phone device add |
Add a new device/extension |
claude-phone device list |
List configured devices |
claude-phone device remove <name> |
Remove a device |
claude-phone logs [service] |
Tail logs (voice-app, drachtio, freeswitch) |
claude-phone config show |
Display configuration (secrets redacted) |
claude-phone config path |
Show config file location |
claude-phone config reset |
Reset configuration |
claude-phone backup |
Create configuration backup |
claude-phone restore |
Restore from backup |
claude-phone update |
Update Claude Phone |
claude-phone uninstall |
Complete removal |
Each SIP extension can have its own identity with a unique name, voice, and personality prompt:
claude-phone device addExample devices:
- Morpheus (ext 9000) - General assistant
- Cephanie (ext 9002) - Storage monitoring bot
The voice-app exposes these endpoints on port 3000:
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /api/outbound-call |
Initiate an outbound call |
| GET | /api/call/:callId |
Get call status |
| GET | /api/calls |
List active calls |
| POST | /api/query |
Query a device programmatically |
| GET | /api/devices |
List configured devices |
See Outbound API Reference for details.
claude-phone doctor # Automated health checks
claude-phone status # Service status
claude-phone logs # View logs| Problem | Likely Cause | Solution |
|---|---|---|
| Calls connect but no audio | Wrong external IP | Re-run claude-phone setup, verify LAN IP |
| Extension not registering | 3CX SBC not running | Check 3CX admin panel |
| "Sorry, something went wrong" | API server unreachable | Check claude-phone status |
| Port conflict on startup | 3CX SBC using port 5060 | Setup auto-detects this; re-run setup |
See Troubleshooting Guide for more.
Configuration is stored in ~/.claude-phone/config.json with restricted permissions (chmod 600).
claude-phone config show # View config (secrets redacted)
claude-phone config path # Show file location# Run tests
npm test
# Lint
npm run lint
npm run lint:fix- CLI Reference - Detailed CLI documentation
- Troubleshooting - Common issues and solutions
- Outbound API - Outbound calling API reference
- Deployment - Production deployment guide
- Claude Code Skill - Build a "call me" skill for Claude Code
MIT