claude-phone-local 2.0.0

package/docker/entrypoint.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Bootstraps persistent state in /data, then hands off to supervisord.
+# Everything here is idempotent: it only fetches what is missing, so a restart
+# with a populated ./data volume starts instantly and never re-downloads.
+set -euo pipefail
+
+log() { echo "[bootstrap] $*"; }
+
+: "${EXTERNAL_IP:?must be set to this host LAN IP}"
+export DRACHTIO_SECRET="${DRACHTIO_SECRET:-cymru}"
+export RTP_START="${RTP_START:-30000}"
+export RTP_END="${RTP_END:-30100}"
+# FreeSWITCH binds sofia to the container IP (mrf.xml sip-ip = $${local_ip_v4}),
+# never to loopback. drachtio lives in this same network namespace, so it must
+# be pointed at that same address - advertising 127.0.0.1 would send it to a
+# port nothing is listening on. RTP still advertises EXTERNAL_IP for the SBC.
+FS_SIP_IP="$(hostname -i | awk '{print $1}')"
+export FS_SIP_IP
+log "FreeSWITCH SIP will advertise ${FS_SIP_IP}; RTP will advertise ${EXTERNAL_IP}"
+
+export PIPER_VOICES_DIR=/data/voices
+export HF_HOME=/data/models/huggingface
+
+mkdir -p /data/voices /data/models/huggingface /data/audio /data/config
+
+# --- Piper voices -----------------------------------------------------------
+# VOICES is a space-separated list of Piper voice names. Each is resolved to its
+# path in the rhasspy/piper-voices repo from the language prefix.
+PIPER_BASE="https://huggingface.co/rhasspy/piper-voices/resolve/main"
+VOICES="${PIPER_VOICES:-en_US-lessac-medium hi_IN-priyamvada-medium mr_IN-google-medium}"
+
+voice_repo_path() {
+  # en_US-lessac-medium -> en/en_US/lessac/medium/en_US-lessac-medium
+  local name="$1"
+  local locale="${name%%-*}"            # en_US
+  local rest="${name#*-}"               # lessac-medium
+  local speaker="${rest%%-*}"           # lessac
+  local quality="${rest##*-}"           # medium
+  local lang="${locale%%_*}"            # en
+  echo "${lang}/${locale}/${speaker}/${quality}/${name}"
+}
+
+for v in $VOICES; do
+  if [ -f "/data/voices/${v}.onnx" ]; then
+    log "voice ${v} already present"
+    continue
+  fi
+  path="$(voice_repo_path "$v")"
+  log "downloading voice ${v} ..."
+  if curl -fsSL --retry 3 --retry-delay 2 "${PIPER_BASE}/${path}.onnx" -o "/data/voices/${v}.onnx.part" \
+     && curl -fsSL --retry 3 --retry-delay 2 "${PIPER_BASE}/${path}.onnx.json" -o "/data/voices/${v}.onnx.json"; then
+    mv "/data/voices/${v}.onnx.part" "/data/voices/${v}.onnx"
+    log "voice ${v} ready"
+  else
+    rm -f "/data/voices/${v}.onnx.part"
+    log "WARNING: could not download voice ${v} - it will be unavailable"
+  fi
+done
+
+# --- Whisper model ----------------------------------------------------------
+# faster-whisper pulls the model on first use into HF_HOME, which lives on the
+# /data volume, so it survives restarts. Pre-fetch it so the first call is fast.
+if [ "${PREFETCH_WHISPER:-1}" = "1" ]; then
+  log "ensuring Whisper model '${WHISPER_MODEL:-medium}' is cached (first run may take a while) ..."
+  /opt/venv/bin/python - <<'PY' || log "WARNING: Whisper prefetch failed; it will download on first call"
+import os
+from faster_whisper import WhisperModel
+WhisperModel(
+    os.environ.get("WHISPER_MODEL", "medium"),
+    device=os.environ.get("WHISPER_DEVICE", "cpu"),
+    compute_type=os.environ.get("WHISPER_COMPUTE_TYPE", "int8"),
+)
+print("[bootstrap] whisper model cached")
+PY
+fi
+
+# --- Device config ----------------------------------------------------------
+# Seed /data/config/devices.json once, then never touch it again - it holds the
+# user's SIP credentials and is theirs to edit.
+if [ ! -f /data/config/devices.json ]; then
+  if [ -n "${SIP_EXTENSION:-}" ]; then
+    log "generating devices.json for extension ${SIP_EXTENSION}"
+    /usr/bin/node -e '
+      const fs = require("fs");
+      const ext = process.env.SIP_EXTENSION;
+      fs.writeFileSync("/data/config/devices.json", JSON.stringify({
+        [ext]: {
+          name: process.env.DEVICE_NAME || "Maya",
+          extension: ext,
+          authId: process.env.SIP_AUTH_ID || ext,
+          password: process.env.SIP_PASSWORD || "",
+          voice: process.env.PIPER_VOICE || "en_US-lessac-medium",
+          language: process.env.STT_LANGUAGE || "auto",
+          prompt: process.env.DEVICE_PROMPT ||
+            "You are " + (process.env.DEVICE_NAME || "Maya") +
+            ", a helpful AI assistant speaking to the user over the phone. " +
+            "ALWAYS reply in the same language the user just used, using that " +
+            "language native script. Keep voice responses under 40 words."
+        }
+      }, null, 2) + "\n");
+    '
+  else
+    log "SIP_EXTENSION not set - skipping devices.json generation"
+  fi
+else
+  log "devices.json already present (left untouched)"
+fi
+
+log "bootstrap complete - starting services"
+exec /usr/bin/supervisord -c /etc/supervisor/supervisord.conf

package/docker/supervisord.conf

@@ -0,0 +1,78 @@
+; claude-phone-local - all five services in one container.
+; Everything talks over 127.0.0.1 here, which is why the unified image needs no
+; Docker DNS names and sidesteps the bridge-networking issues of the split setup.
+[supervisord]
+nodaemon=true
+logfile=/dev/null
+logfile_maxbytes=0
+pidfile=/run/supervisord.pid
+user=root
+
+[program:freeswitch]
+command=/entrypoint.sh freeswitch
+  --sip-port 5080
+  --rtp-range-start %(ENV_RTP_START)s
+  --rtp-range-end %(ENV_RTP_END)s
+  --ext-rtp-ip %(ENV_EXTERNAL_IP)s
+  --ext-sip-ip %(ENV_FS_SIP_IP)s
+  --advertise-external-ip
+  -- -nc -nf
+priority=10
+autorestart=true
+startsecs=5
+stdout_logfile=/dev/fd/1
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/fd/2
+stderr_logfile_maxbytes=0
+stdout_events_enabled=true
+
+[program:drachtio]
+command=/usr/local/bin/drachtio
+  --contact sip:*:5070;transport=tcp,udp
+  --external-ip %(ENV_EXTERNAL_IP)s
+  --secret %(ENV_DRACHTIO_SECRET)s
+  --port 9022
+  --loglevel info
+priority=10
+autorestart=true
+startsecs=3
+stdout_logfile=/dev/fd/1
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/fd/2
+stderr_logfile_maxbytes=0
+
+[program:stt]
+command=/opt/venv/bin/uvicorn server:app --host 127.0.0.1 --port 9001
+directory=/opt/stt
+environment=HF_HOME="/data/models/huggingface",HOME="/root"
+priority=20
+autorestart=true
+; the first run downloads the Whisper model, which can take several minutes
+startsecs=10
+stdout_logfile=/dev/fd/1
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/fd/2
+stderr_logfile_maxbytes=0
+
+[program:tts]
+command=/opt/venv/bin/uvicorn server:app --host 127.0.0.1 --port 9002
+directory=/opt/tts
+environment=PIPER_VOICES_DIR="/data/voices"
+priority=20
+autorestart=true
+startsecs=5
+stdout_logfile=/dev/fd/1
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/fd/2
+stderr_logfile_maxbytes=0
+
+[program:voice-app]
+command=/usr/bin/node index.js
+directory=/app
+priority=30
+autorestart=true
+startsecs=5
+stdout_logfile=/dev/fd/1
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/fd/2
+stderr_logfile_maxbytes=0

package/docker-compose.yml

@@ -0,0 +1,40 @@
+# claude-phone-local - one container, one volume.
+#
+# All five services (drachtio, FreeSWITCH, voice-app, STT, TTS) run inside a
+# single image and talk over 127.0.0.1, so there is no container DNS to get
+# wrong. Everything that must survive a restart lives in ./data:
+#
+#   ./data/voices   Piper voice models   (downloaded on first run)
+#   ./data/models   Whisper model cache  (downloaded on first run)
+#   ./data/config   devices.json         (generated once, then yours to edit)
+#   ./data/audio    generated speech     (scratch)
+#
+# The previous five-container layout is preserved in docker-compose.multi.yml.
+#
+# EXTERNAL_IP in .env must be this PC's LAN IP (run `ipconfig` / `ip addr`) --
+# it is the address 3CX sends SIP and RTP to.
+
+services:
+  claude-phone:
+    build: .
+    image: claude-phone-local:latest
+    container_name: claude-phone
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      # Everything is in-process now, so all hosts are loopback.
+      - DRACHTIO_HOST=127.0.0.1
+      - FREESWITCH_HOST=127.0.0.1
+      - STT_LOCAL_URL=http://127.0.0.1:9001
+      - TTS_LOCAL_URL=http://127.0.0.1:9002
+      - AUDIO_BASE_URL=http://127.0.0.1:3000
+      - RTP_START=30000
+      - RTP_END=30100
+    ports:
+      - "3000:3000"                      # HTTP API + audio file serving
+      - "5070:5070/udp"                  # drachtio SIP
+      - "5070:5070/tcp"
+      - "30000-30100:30000-30100/udp"    # RTP
+    volumes:
+      - ./data:/data

package/docs/CLAUDE-CODE-SKILL.md

@@ -0,0 +1,45 @@
+# Claude Code Call Skill — superseded
+
+> **This approach has been replaced by the [MCP server](MCP-SERVER.md).**
+
+This document used to describe a Python-based Claude Code *skill* that wrapped
+the outbound-call API, so you could say "call me when the backup finishes".
+
+That capability now ships as a proper **MCP server** (`mcp-server/`), which is
+better in every way that matters here:
+
+| | Old skill | MCP server |
+|---|---|---|
+| Integration | Python script invoked by a skill | Native MCP tools |
+| Discovery | Claude had to be told it existed | Advertised via `tools/list` |
+| Errors | Raised as script output | Returned as tool errors Claude can act on |
+| Install | Copy files into a skills directory | `claude mcp add` |
+| Status/hangup | Manual HTTP calls | `call_status`, `hangup` tools |
+
+## Use this instead
+
+```bash
+cd mcp-server && npm install
+
+claude mcp add claude-phone --scope user \
+  --env PHONE_DEFAULT_TO=17510 \
+  -- node /absolute/path/to/mcp-server/index.js
+```
+
+Restart Claude Code, then just ask:
+
+> "Run the migration and call me if anything needs a decision."
+
+Full documentation: **[MCP-SERVER.md](MCP-SERVER.md)**.
+
+## If you still want the old skill
+
+It remains in git history. To recover it:
+
+```bash
+git log --oneline -- docs/CLAUDE-CODE-SKILL.md
+git show <commit>:docs/CLAUDE-CODE-SKILL.md > old-skill.md
+```
+
+The underlying HTTP API it called (`POST /api/outbound-call`) is unchanged and
+still supported — see [../voice-app/README-OUTBOUND.md](../voice-app/README-OUTBOUND.md).

package/docs/LANGUAGES.md

@@ -0,0 +1,113 @@
+# Languages — English, Hindi, Marathi
+
+Speech is fully offline in all three. Whisper detects the language of each
+utterance, and the reply comes back in that same language with a matching voice.
+
+## How it works
+
+```
+you speak
+   → faster-whisper transcribes AND reports the language code  (hi / mr / en)
+   → the code picks a Piper voice from LANG_VOICE_MAP
+   → Claude is instructed to reply in the same language
+   → Piper speaks it in that voice
+```
+
+Detection is **per utterance**, so you can switch language mid-call and she
+follows.
+
+## Configuration
+
+```bash
+STT_LANGUAGE=auto          # detect per utterance; or pin to en | hi | mr
+SUPPORTED_LANGS=en,hi,mr   # languages we will answer in
+LANG_VOICE_MAP={"en":"en_US-lessac-medium","hi":"hi_IN-priyamvada-medium","mr":"mr_IN-google-medium"}
+WHISPER_MODEL=medium       # see accuracy below
+```
+
+`SUPPORTED_LANGS` is a safety net, not decoration. Whisper can return any of
+~99 codes but only the installed voices exist on disk. A code outside this list
+falls back to the device voice, so a misdetection — `ne` for Marathi is very
+plausible, both are Devanagari — costs you the wrong accent rather than a 404
+mid-call.
+
+## Voices
+
+Downloaded automatically on first run into `data/voices/`:
+
+| Language | Voice | Size |
+|---|---|---|
+| English | `en_US-lessac-medium` | 61 MB |
+| Hindi | `hi_IN-priyamvada-medium` | 61 MB |
+| Marathi | `mr_IN-google-medium` | 73 MB |
+
+Change the set with `PIPER_VOICES` (space-separated) in `.env`; the entrypoint
+resolves each name to its path in the
+[rhasspy/piper-voices](https://huggingface.co/rhasspy/piper-voices) repo.
+
+Other English voices worth trying: `en_US-amy-medium`, `en_US-kristin-medium`,
+`en_US-hfc_female-medium`, `en_US-ryan-high`.
+
+```bash
+curl http://127.0.0.1:9002/voices   # what is actually installed
+```
+
+## Accuracy — read this before judging Marathi
+
+Measured on this stack:
+
+| Language | `small` | `medium` |
+|---|---|---|
+| English | good | very good |
+| Hindi | fair | **very good** |
+| Marathi | poor | **fair** |
+
+Whisper's Marathi training data is thin compared with Hindi. Detection is
+reliable in both; it is the *words* that suffer in Marathi.
+
+`large-v3` improves Marathi noticeably but is ~3 GB and materially slower per
+turn on CPU — a real cost on a live call, where every second is dead air.
+
+## The speed/accuracy trade-off
+
+`WHISPER_MODEL` is the single biggest latency lever:
+
+| Model | Transcription | Notes |
+|---|---|---|
+| `small` | ~4s | fine for English, weak on Marathi |
+| `medium` | ~14s | needed for solid Hindi/Marathi |
+| `large-v3` | ~40s+ | best accuracy, painful on a phone call |
+
+If you mostly speak English, `small` makes calls feel dramatically snappier.
+Keep `medium` while testing the Indian languages.
+
+## Making her reply in the right language
+
+Transcription alone is not enough — Claude has to be told, or she will answer a
+Hindi question in English. The device prompt in `data/config/devices.json`
+handles it:
+
+> ALWAYS reply in the same language the user just used, using that language's
+> native script (Devanagari for Hindi and Marathi). Never transliterate.
+
+The "never transliterate" clause matters: Piper's Hindi and Marathi voices read
+**Devanagari**. Hand them romanised Hindi ("aap kaise hain") and you get an
+English speaker mangling syllables.
+
+## Ending a call
+
+Goodbye phrases are recognised in all three languages, including
+`बंद करो`, `फोन बंद करो`, `ठेवतो`, `अलविदा`, `बाय`, plus romanised forms
+(`band karo`, `alvida`). See `goodbyePhrases` in `voice-app/lib/sip-handler.js`.
+
+## Adding another language
+
+1. Find a voice in the [Piper catalogue](https://huggingface.co/rhasspy/piper-voices)
+   (56 languages available).
+2. Add its name to `PIPER_VOICES` in `.env`.
+3. Add the Whisper code → voice mapping to `LANG_VOICE_MAP`.
+4. Add the code to `SUPPORTED_LANGS`.
+5. Add goodbye phrases for it in `sip-handler.js`.
+6. `docker compose restart claude-phone` — the entrypoint downloads it on boot.
+
+No image rebuild is needed; voices live on the `./data` volume.

package/docs/MCP-SERVER.md

@@ -0,0 +1,111 @@
+# MCP Server — let Claude phone you
+
+Gives a Claude Code session a phone. It can ring you mid-task, say why, and —
+in conversation mode — talk the decision through before carrying on.
+
+Useful when Claude is doing something long and hits a fork in the road: a
+migration that needs a call, a deploy that wants confirmation, a test suite that
+went red in a way worth discussing.
+
+## How it fits
+
+The MCP server does **no SIP work**. It is a thin wrapper over the voice-app
+HTTP API that already existed:
+
+```
+Claude Code session
+      │  MCP (stdio)
+      ▼
+mcp-server/index.js
+      │  HTTP
+      ▼
+voice-app /api/outbound-call   →  drachtio → FreeSWITCH → 3CX → your phone
+```
+
+## Install
+
+```bash
+cd mcp-server && npm install
+
+claude mcp add claude-phone --scope user \
+  --env VOICE_APP_URL=http://127.0.0.1:3000 \
+  --env PHONE_DEFAULT_TO=17510 \
+  -- node /absolute/path/to/mcp-server/index.js
+```
+
+Then **restart Claude Code** and confirm:
+
+```bash
+claude mcp list
+# claude-phone: node …/mcp-server/index.js - ✔ Connected
+```
+
+| Env | Purpose |
+|---|---|
+| `VOICE_APP_URL` | Where voice-app listens (default `http://127.0.0.1:3000`) |
+| `PHONE_DEFAULT_TO` | Number/extension to ring when `to` is omitted |
+
+## Tools
+
+### `call_me`
+
+Rings you and speaks a message.
+
+| Arg | Required | Notes |
+|---|---|---|
+| `message` | yes | What to say. One or two spoken sentences, no markdown. |
+| `mode` | no | `announce` (say it, hang up) or `converse` (stay on the line) |
+| `to` | no | Defaults to `PHONE_DEFAULT_TO` |
+| `context` | no | Background so the voice agent can field follow-ups |
+
+### `call_status`
+
+Poll a call by `callId` — whether it is still up and how it ended.
+
+### `hangup`
+
+End a call that is still in progress.
+
+## Using it
+
+Just ask in plain language:
+
+> "Run the migration, and call me if anything needs a decision."
+
+> "This test suite takes 20 minutes — phone me when it finishes with a summary."
+
+Claude picks the tool itself. For a back-and-forth, ask for conversation mode:
+
+> "Call me and talk me through the options — I want to answer, not just listen."
+
+## Writing a good message
+
+It is **spoken aloud**, so:
+
+- Keep it to one or two sentences.
+- No markdown, code blocks, paths, or long identifiers — they sound terrible.
+- Lead with the decision, not the backstory:
+  *"The migration is ready but will drop two columns — should I continue?"*
+- Use `context` for the detail. It never gets read out, but the voice agent can
+  draw on it when you ask a follow-up question.
+
+## Notes and limits
+
+- **voice-app must be running** (`docker compose up -d`) — the MCP server only
+  proxies to it.
+- **`announce` does not wait.** It returns as soon as the call starts. Poll
+  `call_status` if you need the outcome.
+- **If you do not answer**, the call ends on the ring timeout
+  (`OUTBOUND_RING_TIMEOUT`, default 30s) and `call_status` reports it. Claude
+  should carry on rather than block.
+- Errors come back as tool failures with the HTTP status, so Claude can react
+  instead of crashing.
+
+## Troubleshooting
+
+| Symptom | Check |
+|---|---|
+| `✘ Failed to connect` in `claude mcp list` | `cd mcp-server && npm install`; use an absolute path in the registration |
+| `claude-phone: 500 …` | Is voice-app up? `curl http://127.0.0.1:3000/api/devices` |
+| Phone never rings | SIP registration — `docker logs claude-phone \| grep MULTI-REGISTRAR` |
+| Rings, then silence | Same RTP/SDP checks as inbound: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) |