claude-phone-local 2.0.0

package/mcp-server/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "claude-phone-mcp",
+  "version": "1.0.0",
+  "description": "MCP server letting a Claude Code session phone the user and talk it through.",
+  "type": "module",
+  "bin": {
+    "claude-phone-mcp": "./index.js"
+  }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "claude-phone-local",
+  "version": "2.0.0",
+  "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": {
+    "claude-phone": "cli/bin/claude-phone.js"
+  },
+  "files": [
+    "cli/bin",
+    "cli/lib",
+    "cli/README.md",
+    "voice-app",
+    "claude-api-server",
+    "stt-local",
+    "tts-local",
+    "Dockerfile",
+    "mcp-server",
+    "docker",
+    "docker-compose.yml",
+    ".env.example",
+    "README.md",
+    "docs",
+    "!voice-app/config/devices.json",
+    "!voice-app/audio/**",
+    "!voice-app/audio-temp/**",
+    "!tts-local/voices/**",
+    "!**/.env",
+    "!**/node_modules/**"
+  ],
+  "scripts": {
+    "postinstall": "node ./cli/bin/postinstall.js || true",
+    "prepublishOnly": "node ./cli/bin/check-publish-safety.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "voice",
+    "sip",
+    "3cx",
+    "ai",
+    "whisper",
+    "piper",
+    "offline",
+    "self-hosted",
+    "hindi",
+    "marathi",
+    "multilingual",
+    "voip",
+    "freeswitch",
+    "drachtio"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "inquirer": "^9.2.15",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "axios": "^1.6.7",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theNetworkChuck/claude-phone.git"
+  }
+}

package/stt-local/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+RUN pip install --no-cache-dir fastapi uvicorn[standard] python-multipart faster-whisper
+
+COPY server.py /app/server.py
+
+EXPOSE 9001
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "9001"]

package/stt-local/server.py

@@ -0,0 +1,45 @@
+"""
+Local speech-to-text sidecar for claude-phone.
+Wraps faster-whisper behind a tiny HTTP API so voice-app (Node) can call it
+the same way it used to call OpenAI's Whisper API — except fully offline.
+
+POST /transcribe   multipart form: file=<wav bytes>, language=en|hi|mr|auto
+                    -> {"text": "...", "language": "hi"}
+                    language=auto (or empty) lets Whisper detect it and the
+                    detected code comes back so the caller can pick a matching
+                    TTS voice.
+GET  /health        -> {"status": "ok", "model": "small"}
+"""
+
+import io
+import os
+
+from fastapi import FastAPI, UploadFile, Form
+from faster_whisper import WhisperModel
+
+MODEL_SIZE = os.environ.get("WHISPER_MODEL", "small")
+DEVICE = os.environ.get("WHISPER_DEVICE", "cpu")
+COMPUTE_TYPE = os.environ.get("WHISPER_COMPUTE_TYPE", "int8")
+
+app = FastAPI(title="claude-phone local STT")
+
+print(f"[stt-local] loading faster-whisper '{MODEL_SIZE}' ({DEVICE}/{COMPUTE_TYPE})...")
+model = WhisperModel(MODEL_SIZE, device=DEVICE, compute_type=COMPUTE_TYPE)
+print("[stt-local] model ready")
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "model": MODEL_SIZE}
+
+
+@app.post("/transcribe")
+async def transcribe(file: UploadFile, language: str = Form("en")):
+    audio_bytes = await file.read()
+    # "auto"/"" -> None makes faster-whisper detect the language itself.
+    lang = None if language in ("auto", "", None) else language
+    segments, info = model.transcribe(
+        io.BytesIO(audio_bytes), language=lang, vad_filter=True
+    )
+    text = " ".join(seg.text.strip() for seg in segments).strip()
+    return {"text": text, "language": info.language}

package/tts-local/Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+RUN pip install --no-cache-dir fastapi uvicorn[standard] piper-tts
+
+COPY server.py /app/server.py
+
+EXPOSE 9002
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "9002"]

package/tts-local/server.py

@@ -0,0 +1,83 @@
+"""
+Local text-to-speech sidecar for claude-phone.
+Wraps Piper behind a tiny HTTP API so voice-app (Node) can call it the same
+way it used to call ElevenLabs — except fully offline.
+
+POST /speak   json: {"text": "...", "voice": "en_US-lessac-medium"}
+              -> raw WAV bytes
+
+GET  /voices  -> {"voices": ["en_US-lessac-medium", ...]}  (installed models)
+GET  /health  -> {"status": "ok"}
+"""
+
+import glob
+import os
+import subprocess
+import tempfile
+
+from fastapi import FastAPI, Response
+from pydantic import BaseModel
+
+VOICES_DIR = os.environ.get("PIPER_VOICES_DIR", "/voices")
+DEFAULT_VOICE = os.environ.get("PIPER_VOICE", "en_US-lessac-medium")
+
+app = FastAPI(title="claude-phone local TTS")
+
+
+class SpeakRequest(BaseModel):
+    text: str
+    voice: str | None = None
+
+
+def voice_paths(voice: str):
+    model = os.path.join(VOICES_DIR, f"{voice}.onnx")
+    config = os.path.join(VOICES_DIR, f"{voice}.onnx.json")
+    return model, config
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+
+@app.get("/voices")
+def voices():
+    names = sorted(
+        os.path.splitext(os.path.basename(p))[0]
+        for p in glob.glob(os.path.join(VOICES_DIR, "*.onnx"))
+    )
+    return {"voices": names}
+
+
+@app.post("/speak")
+def speak(req: SpeakRequest):
+    voice = req.voice or DEFAULT_VOICE
+    model, config = voice_paths(voice)
+
+    if not os.path.exists(model):
+        return Response(
+            content=f"Voice model not found: {model}. Download it into {VOICES_DIR}/ "
+                     f"(see README) and restart tts-local.".encode(),
+            status_code=404,
+            media_type="text/plain",
+        )
+
+    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tf:
+        out_path = tf.name
+
+    try:
+        subprocess.run(
+            ["piper", "--model", model, "--config", config, "--output_file", out_path],
+            input=req.text.encode("utf-8"),
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+        )
+        with open(out_path, "rb") as f:
+            wav_bytes = f.read()
+        return Response(content=wav_bytes, media_type="audio/wav")
+    finally:
+        try:
+            os.unlink(out_path)
+        except OSError:
+            pass

package/voice-app/API-QUERY-CONTRACT.md

@@ -0,0 +1,238 @@
+# API Contract: Device Personality Query Endpoint
+**Version:** 1.0.0  
+**Status:** DRAFT  
+**Author:** Glenn (The Researcher)  
+**Date:** 2025-12-22  
+
+## 1. Overview
+This specification defines the contract for the `POST /api/query` endpoint in the `voice-app` service. This endpoint allows external systems (specifically n8n automation workflows) to synchronously query specific device personalities (e.g., "Cephanie", "Morpheus") without initiating a voice call.
+
+The primary goal is to retrieve **Structured JSON** responses from the LLM to drive conditional logic in automation flows.
+
+## 2. Base Configuration
+- **Host:** `http://10.70.7.81:3000` (Sippycup)
+- **Content-Type:** `application/json`
+- **Auth:** Internal Network Only (No token required for MVP)
+
+## 3. Configuration Dependencies
+The system relies on a `devices.json` configuration file to map identifiers to personalities.
+
+**Definition (`devices.json`):**
+```json
+{
+  "9002": {
+    "name": "Cephanie",
+    "extension": "9002",
+    "voiceId": "gjV6HdJf5tTxacPrkBXH",
+    "systemPrompt": "You are Cephanie, Chuck's NAS. You are sassy, cynical, and technical. You hate rebooting."
+  },
+  "9003": {
+    "name": "Morpheus",
+    "extension": "9003",
+    "voiceId": "...",
+    "systemPrompt": "You are Morpheus, the wise AI overseer..."
+  }
+}
+```
+
+## 4. Endpoint Specification
+
+### `POST /api/query`
+
+Directly queries a device personality with a text prompt and receives a text or JSON response.
+
+#### 4.1 Request Schema
+
+```json
+{
+  "target": "string (required)",
+  "query": "string (required)",
+  "format": "string (optional, default: 'text')",
+  "timeout": "number (optional, default: 60)"
+}
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description | Validation | 
+|-------|------|----------|-------------|------------|
+| `target` | string | Yes | The identifier of the device to query. Can be an **Extension** (e.g., "9002") or a **Name** (case-insensitive, e.g., "cephanie"). | Must match an entry in `devices.json`. |
+| `query` | string | Yes | The input prompt or question for the device. | Min 1 char, Max 2000 chars. |
+| `format` | string | No | The desired output format. Options: `text` (conversational), `json` (structured). | Enum: `['text', 'json']` |
+| `timeout` | number | No | Request timeout in seconds. LLMs can be slow. | Max 120. |
+
+#### 4.2 Response Schema
+
+**Success Response (200 OK)**
+
+```json
+{
+  "success": true,
+  "timestamp": "2025-12-22T10:00:00.000Z",
+  "device": {
+    "name": "Cephanie",
+    "extension": "9002"
+  },
+  "response": {
+    "raw": "string",
+    "data": "object | null",
+    "format": "string"
+  },
+  "meta": {
+    "duration_ms": 1450,
+    "model": "claude-3-opus"
+  }
+}
+```
+
+**Field Details:**
+
+- `response.raw`: The exact string returned by the LLM.
+- `response.data`: 
+    - If `format="json"`, this contains the parsed JSON object.
+    - If `format="text"`, this is `null`.
+    - If JSON parsing fails, this is `null` (check `error` in logs, or `success: false` if strict).
+
+**Error Response (4xx/5xx)**
+
+```json
+{
+  "success": false,
+  "error": "string (code)",
+  "message": "string (human readable)",
+  "details": "object (optional)"
+}
+```
+
+**Common Error Codes:**
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `device_not_found` | 404 | The `target` did not match any configured device. |
+| `validation_error` | 400 | Missing fields or invalid format. |
+| `llm_timeout` | 504 | The LLM did not respond within the timeout window. |
+| `llm_error` | 502 | The upstream Claude API server failed. |
+| `parse_error` | 422 | `format="json"` was requested, but the LLM returned invalid JSON. |
+
+---
+
+
+## 5. Structured Output Strategy (JSON)
+
+When `format: "json"` is requested, the `voice-app` MUST inject specific instructions into the System Prompt sent to Claude.
+
+**System Prompt Injection:**
+
+```text
+[Original Device Persona]
+
+IMPORTANT: You are currently acting as an API endpoint.
+1. You must respond ONLY with valid JSON.
+2. Do not include markdown formatting (like ```json).
+3. Do not include conversational filler before or after the JSON.
+4. Your response will be parsed by a machine.
+
+Required JSON Structure:
+{
+  "approved": boolean,
+  "reason": "string (short explanation)",
+  "metadata": { ...any relevant data... }
+}
+```
+
+**Retry Logic (Internal):**
+If the LLM returns text with markdown ticks (e.g., \`\`\`json ... \`\`\`), the `voice-app` parser should aggressively strip them before `JSON.parse()`.
+
+---
+
+
+## 6. n8n Integration Guide
+
+### 6.1 HTTP Request Node Configuration
+
+- **Method:** POST
+- **URL:** `http://10.70.7.81:3000/api/query`
+- **Body Parameters:**
+  ```json
+  {
+    "target": "Cephanie",
+    "query": "Is the server room temperature okay? It's currently 72F.",
+    "format": "json"
+  }
+  ```
+
+### 6.2 The IF Node (Conditional Logic)
+
+Assuming the n8n HTTP Node outputs the API response, you can route based on the device's decision.
+
+**Scenario:** "Ask Cephanie if I can reboot the server."
+
+**Response Data (`body.response.data`):**
+```json
+{
+  "approved": false,
+  "reason": "I am currently scrubbing the filesystem. Do not touch me.",
+  "metadata": { "job_id": "scrub_291" }
+}
+```
+
+**IF Node Expression:**
+
+*Condition: Boolean*
+
+```javascript
+// Expression to check approval
+{{ $json.body.response.data.approved }}
+```
+
+**Fallback Expression (Safety):**
+
+If parsing fails, default to `false`:
+
+```javascript
+{{ $json.body.response.data ? $json.body.response.data.approved : false }}
+```
+
+## 7. Example Scenarios
+
+### Scenario A: Simple Status Check (Text)
+**Request:**
+```json
+{ "target": "Morpheus", "query": "Who is currently connected?", "format": "text" }
+```
+**Response:**
+```json
+{
+  "success": true,
+  "response": {
+    "raw": "Currently, only Agent Smith is connected via the neural link.",
+    "data": null,
+    "format": "text"
+  }
+}
+```
+
+### Scenario B: Automation Decision (JSON)
+**Request:**
+```json
+{ 
+  "target": "Cephanie", 
+  "query": "Alert: Disk usage at 90%. Should we expand volume?", 
+  "format": "json" 
+}
+```
+**Response:**
+```json
+{
+  "success": true,
+  "response": {
+    "raw": "{\"approved\": true, \"reason\": \"90% is critical threshold. Expand immediately.\", \"metadata\": { \"urgent\": true }}",
+    "data": {
+      "approved": true,
+      "reason": "90% is critical threshold. Expand immediately.",
+      "metadata": { "urgent": true }
+    },
+    "format": "json"
+  }
+}
+```

package/voice-app/DEPLOYMENT.md

@@ -0,0 +1,176 @@
+# Deployment
+
+Running claude-phone-local beyond a first test. For the quickstart see
+[../README.md](../README.md); for architecture see [../CLAUDE.md](../CLAUDE.md).
+
+## Topology
+
+Two moving parts:
+
+| Where | What | Why there |
+|---|---|---|
+| Container | drachtio, FreeSWITCH, voice-app, STT, TTS | one image, supervisord, all loopback |
+| Host | `claude-api-server` → `claude` CLI | the CLI is installed and authenticated on the host |
+
+They meet at exactly one place: `host.docker.internal:3333`.
+
+## Ports
+
+| Port | Proto | Published | Purpose |
+|---|---|---|---|
+| 5070 | UDP/TCP | yes | drachtio SIP — the PBX talks to this |
+| 30000–30100 | UDP | yes | RTP media |
+| 3000 | TCP | yes | voice-app HTTP API |
+| 5080 | UDP/TCP | **no** | FreeSWITCH SIP — internal only |
+| 8021 | TCP | **no** | FreeSWITCH ESL — internal only |
+| 9001 / 9002 | TCP | loopback | STT / TTS sidecars |
+| 3333 | TCP | host | claude-api-server |
+
+5080 and 8021 are deliberately unpublished: drachtio reaches FreeSWITCH inside
+the container. Publishing them would expose your media server to the LAN.
+
+RTP is **30000–30100** because the 3CX SBC uses 20000–20099; overlapping the two
+breaks audio.
+
+### Firewall
+
+```powershell
+New-NetFirewallRule -DisplayName "claude-phone SIP" -Direction Inbound `
+  -Protocol UDP -LocalPort 5070 -Action Allow
+New-NetFirewallRule -DisplayName "claude-phone RTP" -Direction Inbound `
+  -Protocol UDP -LocalPort 30000-30100 -Action Allow
+```
+
+Do **not** open 3333. See [Security](#security).
+
+## Networking and NAT
+
+Docker Desktop cannot do real host networking on Windows, so the compose file
+uses a bridge with published ports. FreeSWITCH therefore cannot discover your
+LAN address and must be told it.
+
+The critical detail — SIP and RTP advertise **different** addresses:
+
+```
+ext_rtp_ip = EXTERNAL_IP     e.g. 172.16.14.225   (so the SBC reaches the media)
+ext_sip_ip = container IP    e.g. 172.18.0.2      (so drachtio reaches FreeSWITCH)
+```
+
+`docker/entrypoint.sh` computes the container IP at boot. Verify after a deploy:
+
+```bash
+docker logs claude-phone | grep "will advertise"
+# [bootstrap] FreeSWITCH SIP will advertise 172.18.0.2; RTP will advertise 172.16.14.225
+```
+
+FreeSWITCH's `nat.auto` ACL also has to be defused — it treats `172.16.0.0/12`
+as local, which swallows both a `172.16.x` LAN and the `172.18.x` Docker bridge.
+The Dockerfile patches `mrf.xml` with `local-network-acl = none` at build time.
+
+## Persistent state
+
+Everything that must survive a restart is on the `./data` bind mount:
+
+```
+data/voices/          Piper models      (~195 MB)
+data/models/          Whisper cache     (~1.9 GB)
+data/config/          devices.json      (your SIP credentials)
+data/audio/           generated speech  (scratch, safe to clear)
+```
+
+Back up `data/config/`. The rest re-downloads on its own.
+
+A healthy restart is under a minute and re-downloads nothing:
+
+```
+[bootstrap] voice en_US-lessac-medium already present
+[bootstrap] whisper model cached
+[bootstrap] devices.json already present (left untouched)
+```
+
+## Running the host wrapper as a service
+
+`claude-api-server` must stay up or calls connect and then fail to answer.
+
+**Windows (NSSM):**
+
+```powershell
+nssm install claude-api "C:\Program Files\nodejs\node.exe" `
+  "C:\path\to\claude-api-server\server.js"
+nssm set claude-api AppEnvironmentExtra CLAUDE_MODEL=claude-sonnet-5
+nssm start claude-api
+```
+
+**Linux (systemd):** `/etc/systemd/system/claude-api.service`
+
+```ini
+[Unit]
+Description=claude-phone API server
+After=network.target
+
+[Service]
+Type=simple
+User=youruser
+WorkingDirectory=/path/to/claude-api-server
+Environment=CLAUDE_MODEL=claude-sonnet-5
+ExecStart=/usr/bin/node server.js
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+It must run **as the user whose Claude Code is authenticated** — it inherits
+that login and config.
+
+## Resource sizing
+
+| | Idle | Per call |
+|---|---|---|
+| RAM | ~2.5 GB (Whisper `medium` resident) | +200 MB |
+| CPU | negligible | 1–2 cores during transcription |
+| Disk | ~2.2 GB in `./data` | a few MB of audio |
+
+`WHISPER_MODEL` dominates memory: `small` ~1 GB, `medium` ~2.5 GB,
+`large-v3` ~5 GB. Transcription is CPU-bound — it is the largest fixed part of
+response latency.
+
+## Monitoring
+
+```bash
+docker compose ps
+docker logs claude-phone 2>&1 | grep -E "MULTI-REGISTRAR|CALL |error"
+curl http://127.0.0.1:3000/api/devices     # voice-app alive
+curl http://127.0.0.1:3333/health          # host wrapper alive
+```
+
+Supervisord restarts any of the five processes that dies. Repeated restarts show
+as `spawned:` lines without a matching `entered RUNNING state`.
+
+SIP registration refreshes every ~27 minutes; losing it silently is the usual
+cause of "calls stopped arriving".
+
+## Security
+
+`claude-api-server` runs the CLI with `--dangerously-skip-permissions`: no
+prompts, every tool, full access to the host as your user, with your normal
+`~/.claude` config including MCP servers and plugins.
+
+- **Bind 3333 to localhost.** Docker Desktop still reaches it through
+  `host.docker.internal`. On a LAN-exposed `0.0.0.0` bind, anyone who can route
+  to the port can execute commands as you.
+- **Never commit** `data/config/devices.json` or `.env`.
+- Consider a dedicated 3CX extension with restricted inbound routing so only
+  your own extensions can dial it.
+
+## Upgrading
+
+```bash
+git pull
+docker compose build
+docker compose up -d
+```
+
+`./data` is untouched, so no models are re-downloaded and `devices.json` is
+preserved. Roll back with `docker compose -f docker-compose.multi.yml up -d`
+(the previous five-container layout) if a build regresses.

package/voice-app/Dockerfile

@@ -0,0 +1,20 @@
+FROM node:20-slim
+
+WORKDIR /app
+
+# Install dependencies first (better caching)
+COPY package*.json ./
+RUN npm install --production
+
+# Copy application code
+COPY . .
+
+# Create audio directory
+RUN mkdir -p /app/audio
+
+# HTTP API port
+EXPOSE 3000
+# WebSocket for audio streaming
+EXPOSE 3001
+
+CMD ["node", "index.js"]