claude-phone-local 2.2.0 → 2.2.2

package/README.md

@@ -134,6 +134,50 @@ claude mcp add claude-phone --scope user \
   -- node /absolute/path/to/mcp-server/index.js
 ```
 
+## What can you do with this?
+
+Since Claude has real shell access to the host PC, "call your extension" is
+really "call a machine that can run anything on your network." Some
+examples:
+
+### Home automation
+
+- **"Turn off the living room lights and lock the front door."** — if your
+  smart home exposes a CLI, API, or Home Assistant instance on the same
+  network, Claude can hit it directly. No separate voice assistant skill to
+  write.
+- **"Is the garage door open?"** — ask a status question from bed without
+  reaching for an app.
+- **"Call me if the washing machine cycle finishes"** — Claude polls
+  something (a smart plug's power draw, a sensor) in the background while
+  doing other work, then rings you via the [MCP server](docs/MCP-SERVER.md)
+  when it's done.
+- **Multilingual household** — parents ask in Hindi or Marathi, kids ask in
+  English, same extension, same session — see [Languages](#languages).
+
+### Inside a company / office
+
+- **"What's the status of the nightly backup job?"** — ask from your car on
+  the way in, get a real answer pulled from actual logs, not a canned reply.
+- **"Restart the staging server and let me know when it's back up."** —
+  fire-and-forget a real ops task, then Claude calls you back when it's
+  actually done (see [Claude calling you](#claude-calling-you)) instead of
+  you babysitting a terminal.
+- **On-call triage** — "walk me through what's alerting right now" while
+  driving, hands-free, with Claude actually querying your monitoring stack
+  instead of reading a static runbook.
+- **A shared team extension** — dial in from any phone (no app, no VPN
+  client) to ask about deploy status, check disk space on a shared box, or
+  kick off a known-safe script — useful when someone's laptop isn't handy but
+  a phone is.
+- **Slack handoff for long tasks** — ask something that takes a while ("audit
+  every repo for hardcoded secrets"), hang up, and have the results posted to
+  a Slack channel instead of waiting on hold.
+
+None of this requires a PBX-side integration or webhook plumbing — it's the
+same shell access you'd have SSH'd into the box yourself, just reachable from
+any phone that can dial the extension.
+
 ## Configuration
 
 Common knobs in `.env`:
@@ -189,6 +233,8 @@ more: **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)**.
 
 ## Documentation
 
+- [docs/SETUP.md](docs/SETUP.md) — full walkthrough: 3CX extension → SBC →
+  Docker → npm install → `claude-phone setup` → `claude-phone start`
 - [CLAUDE.md](CLAUDE.md) — architecture and design decisions
 - [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — every failure mode we hit
 - [docs/LANGUAGES.md](docs/LANGUAGES.md) — Hindi/Marathi setup

package/cli/README.md

@@ -61,17 +61,25 @@ Select this when setting up the Claude API wrapper on a machine with Claude Code
 
 ### Both (All-in-One)
 
-Select this for a single machine running everything.
+Select this for a single machine running everything — most people want this.
+Full prompt-by-prompt walkthrough: [docs/SETUP.md](../docs/SETUP.md).
 
 **What it asks for:**
 1. Local or cloud speech (local = faster-whisper + Piper, no API keys; cloud = ElevenLabs + OpenAI)
-2. 3CX SIP domain and registrar
-3. Device configuration
-4. Server LAN IP, API port, and HTTP port
+2. Whether a 3CX SBC is running on this same PC (auto-avoids its port 5060,
+   and tracks this PC's LAN IP for the registrar automatically)
+3. 3CX SIP domain (and registrar IP, if no local SBC)
+4. Device configuration (name, extension, auth, voice, prompt)
+5. Whether to auto-detect this PC's LAN IP on every `claude-phone start`
+   (recommended — survives network changes without re-running setup), API
+   port, and HTTP port
+6. A callback number for the MCP server (must differ from the device
+   extension — 3CX rejects a device calling itself)
 
 **What `claude-phone start` does:**
 - Starts the `claude-phone` container (drachtio, FreeSWITCH, voice-app, STT, TTS under supervisord)
-- Starts claude-api-server
+- Waits for the voice stack to actually be ready to accept calls
+- Starts claude-api-server and verifies it's healthy before reporting success
 
 ### Pi Auto-Detection
 

package/cli/lib/commands/setup.js

@@ -1253,8 +1253,19 @@ async function setupDevice(config) {
 async function setupServer(config) {
   const localIp = getLocalIP();
 
-  const answers = await inquirer.prompt([
+  const { ipMode } = await inquirer.prompt([
     {
+      type: 'confirm',
+      name: 'ipMode',
+      message: `Auto-detect the LAN IP on every "claude-phone start" (currently ${localIp})? ` +
+        'Recommended if this machine moves networks (laptop, DHCP) - answering ' +
+        'no locks in a fixed IP that goes stale the next time it changes.',
+      default: config.server.externalIp === 'auto' || config.server.externalIp === undefined
+    }
+  ]);
+
+  const answers = await inquirer.prompt([
+    ...(ipMode ? [] : [{
       type: 'input',
       name: 'externalIp',
       message: 'Server LAN IP (for RTP audio):',
@@ -1268,7 +1279,7 @@ async function setupServer(config) {
         }
         return true;
       }
-    },
+    }]),
     {
       type: 'input',
       name: 'claudeApiPort',
@@ -1297,7 +1308,7 @@ async function setupServer(config) {
     }
   ]);
 
-  config.server.externalIp = answers.externalIp;
+  config.server.externalIp = ipMode ? 'auto' : answers.externalIp;
   config.server.claudeApiPort = parseInt(answers.claudeApiPort, 10);
   config.server.httpPort = parseInt(answers.httpPort, 10);
 

package/docker/supervisord.conf

@@ -28,7 +28,7 @@ stdout_events_enabled=true
 
 [program:drachtio]
 command=/usr/local/bin/drachtio
-  --contact sip:*:5070;transport=tcp,udp
+  --contact sip:*:5070;transport=udp
   --external-ip %(ENV_EXTERNAL_IP)s
   --secret %(ENV_DRACHTIO_SECRET)s
   --port 9022

package/docs/SETUP.md

@@ -0,0 +1,245 @@
+# Setup Guide
+
+End-to-end walkthrough for a single-PC install: 3CX extension, SBC, Docker,
+npm install, `claude-phone setup`, `claude-phone start`. Written for the
+"Both (all-in-one)" installation type — everything on one Windows/Mac/Linux
+machine, which is what most people want. For Raspberry Pi split deployments
+see [cli/README.md](../cli/README.md#split-deployment-example).
+
+## Order of operations
+
+1. Create a 3CX extension
+2. Install the 3CX SBC on this PC (only if this PC isn't already inside your
+   3CX network)
+3. Install Docker Desktop
+4. `npm install -g claude-phone-local`
+5. `claude-phone setup`
+6. `claude-phone start`
+
+Do them in this order — `claude-phone setup` asks for the extension's
+credentials, and detects whether a 3CX SBC is already running on this PC.
+
+---
+
+## 1. Create a 3CX extension
+
+In the 3CX Admin Console:
+
+1. **Users → Add User** (or reuse an existing one you don't mind dedicating
+   to this).
+2. Give it an extension number, e.g. `17512`.
+3. Under the user's **SIP/VoIP Devices** or **Authentication** tab, note:
+   - **Extension** (e.g. `17512`)
+   - **Auth ID** — often different from the extension number
+   - **Authentication password**
+4. Note your **3CX domain** too (e.g. `yourcompany.3cx.us` or
+   `1234.3cx.cloud`) — shown in the Admin Console URL or under **General
+   Settings**.
+
+You'll type all four of these into `claude-phone setup` later. Keep this tab
+open.
+
+**Security tip:** don't reuse an extension you actually answer calls on
+personally — Claude answers this one with full shell access to the host
+(see [Security](../README.md#security)). A dedicated extension with
+restricted inbound routing is safer.
+
+## 2. Install the 3CX SBC (only if needed)
+
+Skip this step if this PC is already on the same LAN as your 3CX PBX with no
+NAT/firewall between them — you can register directly against the PBX and
+skip the SBC.
+
+Install the SBC when this PC is remote from the PBX (e.g. cloud-hosted 3CX,
+this PC on a different network) — the SBC is a local relay that keeps the
+inbound SIP path this app cares about all on `127.0.0.1`/LAN, and it's what
+lets you skip poking holes in your firewall for SIP directly to this PC.
+
+1. In 3CX Admin Console: **Admin → SBC → Add SBC**, choose **Generic /
+   Windows**, and follow the download link (or find the "3CX Session Border
+   Controller" installer under downloads for your PBX).
+2. Run the installer on this PC. It'll ask for a **provisioning link** — copy
+   it from the Admin Console's SBC page.
+3. Once installed, the SBC runs as a Windows service (`3CXSBC`) and binds SIP
+   on port **5060**. `claude-phone setup` checks for this automatically later
+   and, if found, tells drachtio (this app's SIP stack) to use port **5070**
+   instead — so the two never fight over the same port.
+4. The SBC config file lives at `C:\ProgramData\3CXSBC\3cxsbc.conf` and
+   normally needs no manual editing — `LocalSipAddr=0.0.0.0` means it
+   self-detects this PC's current LAN IP every time it starts, so it survives
+   network changes (new office, DHCP renewal) without reconfiguration.
+
+## 3. Install Docker Desktop
+
+- Windows/Mac: [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+  — enable the WSL2 backend on Windows during install.
+- Linux: [Docker Engine](https://docs.docker.com/engine/install/) + the
+  Compose plugin.
+
+Verify it's running:
+
+```bash
+docker --version
+docker compose version
+```
+
+You'll also need **Node.js 18+** and the **Claude Code CLI**, logged in
+(`claude --version`).
+
+## 4. Install claude-phone-local
+
+```bash
+npm install -g claude-phone-local
+```
+
+This installs the `claude-phone` CLI globally and automatically installs the
+host-side dependencies for `claude-api-server` and `mcp-server` — no manual
+`npm install` in subfolders needed.
+
+Verify:
+
+```bash
+claude-phone --version
+```
+
+## 5. Run the setup wizard
+
+```bash
+claude-phone setup
+```
+
+It asks these questions, in this order (for "Both (all-in-one)" — the
+default and most common choice):
+
+### Installation type
+
+> **What are you installing?**
+> - Voice Server (Pi/Linux) — this machine only runs the phone/audio side,
+>   talks to a remote API server (e.g. a Raspberry Pi calling out to your
+>   main PC)
+> - API Server — this machine only runs the Claude wrapper, no phone
+>   hardware/Docker here
+> - Both (all-in-one) — full stack on one machine ← most people want this,
+>   and what the rest of this guide walks through
+
+### Speech (STT/TTS) mode
+
+> **How should speech-to-text and text-to-speech work?**
+> - Local (offline, no API keys, no cost) — faster-whisper + Piper, run as
+>   Docker containers, fully private
+> - Cloud (ElevenLabs + OpenAI) — requires paid API keys, higher voice
+>   quality, needs internet
+
+Choosing **Local** then asks:
+- **Piper voice** to use (default `en_US-lessac-medium`) — auto-downloaded
+- **faster-whisper model size** (`tiny`/`base`/`small`/`medium`) — bigger is
+  more accurate but slower; `medium` is recommended for Hindi/Marathi
+
+Choosing **Cloud** asks for an **ElevenLabs API key** (validated live) and a
+default **ElevenLabs voice ID**, then an **OpenAI API key** for Whisper STT.
+
+### SIP / 3CX configuration
+
+Setup first checks port 5060 and the SBC process on its own — if it finds one
+running, the next question defaults to "yes" automatically.
+
+> **Is the 3CX SBC service running on this same PC?**
+
+Answer **yes** if you installed the SBC in step 2. This makes drachtio use
+port 5070 automatically (avoiding the SBC's port 5060) and makes the
+registrar address self-track this PC's current LAN IP on every
+`claude-phone start` — so it survives network changes without re-running
+setup.
+
+Answer **no** if you're registering directly against a remote/cloud 3CX PBX,
+or another SIP provider entirely — you'll then be asked for the registrar IP
+directly.
+
+> **3CX domain** (e.g. `your-3cx.3cx.us`)
+
+The tenant hostname from step 1.
+
+> **3CX registrar IP** (only if you answered "no" above)
+
+The IP/hostname SIP REGISTER requests actually go to.
+
+### Device configuration
+
+This is the extension Claude answers on — the one from step 1.
+
+> **Device name** (e.g. `Maya`)
+> **SIP extension number** (e.g. `17512`)
+> **SIP auth ID**
+> **SIP password**
+> **System prompt** — her personality/instructions, e.g. "You are a helpful
+> AI assistant. Keep voice responses under 40 words."
+
+If you chose **Local** speech mode: **Piper voice for this device** (falls
+back to the default voice you picked earlier). If you chose **Cloud**:
+**ElevenLabs voice ID** (validated live).
+
+### Server configuration
+
+> **Auto-detect the LAN IP on every "claude-phone start"?**
+
+**Recommended: yes.** This is the IP that goes into RTP/SDP so the SBC/PBX
+knows where to send call audio. Auto mode re-detects this PC's current LAN
+IP every time you run `claude-phone start`, so moving between networks
+(home, office, a different Wi-Fi) doesn't require re-running setup. Answering
+no locks in whatever IP is current right now — you'll need to re-run
+`claude-phone setup` if it ever changes.
+
+> **Claude API server port** (default `3333`)
+> **Voice app HTTP port** (default `3000`)
+
+Both are safe to leave at their defaults unless something else on this PC
+already uses them.
+
+### MCP server (lets Claude call you)
+
+> **Number/extension for Claude to call YOU on**
+
+This must be a **different** number from the device extension above — 3CX
+rejects a device calling itself. If you only have the one extension from
+step 1, you'll need a second number here (your mobile, a second 3CX
+extension, or a DID) for the "call me when it's done" feature to work. See
+[Claude calling you](../README.md#claude-calling-you).
+
+Setup then registers the MCP server with your Claude Code CLI automatically.
+
+---
+
+## 6. Start it
+
+```bash
+claude-phone start
+```
+
+This:
+1. Runs prerequisite checks (Node, Docker, disk space, network)
+2. Builds/starts the Docker container (drachtio, FreeSWITCH, voice-app, STT,
+   TTS) — first run downloads ~2GB of speech models, cached in `./data` (well,
+   `~/.claude-phone/data`) for every future start
+3. Waits for the voice stack to actually be ready to accept calls (not just
+   for the container to be up)
+4. Starts `claude-api-server` on the host and verifies it's actually healthy
+
+When you see `✓ All services running!` with your extension listed under
+"Ready to receive calls on", call it.
+
+## Check it worked
+
+```bash
+claude-phone status
+claude-phone doctor           # deeper health check
+claude-phone logs api-server  # host-side Claude wrapper log
+docker logs claude-phone -f   # container-side SIP/voice log
+```
+
+If registration succeeded you'll see a line like:
+
+```
+[MULTI-REGISTRAR] Maya SUCCESS - Registered as ext 17512
+```
+
+Full failure-mode reference: [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-phone-local",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Local/offline fork of NetworkChuck's claude-phone: talk to Claude Code over 3CX/SIP with faster-whisper STT + Piper TTS in one Docker container.",
   "type": "module",
   "bin": {