Claude Phone
January 23, 2026 · View on GitHub
Claude Phone
Voice interface for Claude Code via SIP/3CX. Call your AI, and your AI can call you.
What is this?
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
Prerequisites
| 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 Support
| Platform | Status |
|---|---|
| macOS | Fully supported |
| Linux | Fully supported (including Raspberry Pi) |
| Windows | Not supported (may work with WSL) |
Quick Start
1. Install
curl -sSL https://raw.githubusercontent.com/theNetworkChuck/claude-phone/main/install.sh | bash
The 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
2. Setup
claude-phone setup
The 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 |
3. Start
claude-phone start
Deployment Modes
All-in-One (Single Machine)
Best 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 server
Split Mode (Pi + API Server)
Best 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 containers
On your Mac/Linux (API Server):
claude-phone api-server # Starts Claude API wrapper on port 3333
Note: On the API server machine, you don't need to run claude-phone setup first - the api-server command works standalone.
CLI Commands
| 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 |
Device Personalities
Each SIP extension can have its own identity with a unique name, voice, and personality prompt:
claude-phone device add
Example devices:
- Morpheus (ext 9000) - General assistant
- Cephanie (ext 9002) - Storage monitoring bot
API Endpoints
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.
Troubleshooting
Quick Diagnostics
claude-phone doctor # Automated health checks
claude-phone status # Service status
claude-phone logs # View logs
Common Issues
| 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
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
Development
# Run tests
npm test
# Lint
npm run lint
npm run lint:fix
Documentation
- 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
License
MIT