claude-phone-local 2.0.0

package/.env.example

@@ -0,0 +1,108 @@
+# ====================================
+# Claude Phone Configuration
+# ====================================
+# Copy this to .env and fill in your values
+
+# ====================================
+# Network Configuration
+# ====================================
+
+# Your server's LAN IP (CRITICAL for RTP audio)
+# This IP goes into SDP packets so 3CX knows where to send audio
+EXTERNAL_IP=10.0.0.100
+
+# ====================================
+# Drachtio Configuration
+# ====================================
+
+DRACHTIO_HOST=127.0.0.1
+DRACHTIO_PORT=9022
+DRACHTIO_SECRET=cymru
+
+# SIP port for Contact header (5070 for 3CX SBC mode, 5060 for direct registration)
+# This MUST match the port in docker-compose.yml drachtio command
+DRACHTIO_SIP_PORT=5060
+
+# ====================================
+# FreeSWITCH Configuration
+# ====================================
+
+FREESWITCH_HOST=127.0.0.1
+FREESWITCH_PORT=8021
+FREESWITCH_SECRET=JambonzR0ck$
+
+# ====================================
+# 3CX / SIP Configuration
+# ====================================
+
+# Your 3CX server hostname or IP
+SIP_DOMAIN=your-3cx-server.3cx.us
+SIP_REGISTRAR=10.0.0.50
+
+# Default extension for outbound calls
+SIP_EXTENSION=9000
+SIP_AUTH_ID=your-auth-id
+SIP_PASSWORD=your-password
+
+# Default caller ID for outbound PSTN calls
+DEFAULT_CALLER_ID=+15551234567
+
+# ====================================
+# Claude API Server
+# ====================================
+
+# URL to your Claude API server (runs on your API server with Claude Max)
+CLAUDE_API_URL=http://10.0.0.200:3333
+
+# ====================================
+# Speech-to-text / Text-to-speech mode
+# ====================================
+# "local"  = faster-whisper + Piper, run as Docker containers here, no API keys
+# "cloud"  = original ElevenLabs (TTS) + OpenAI (STT), requires paid API keys
+
+STT_MODE=local
+TTS_MODE=local
+
+# ---- local mode settings ----
+# These use Docker service names (bridge network) — correct default for
+# Docker Desktop on Windows. Only change to 127.0.0.1 if you switch to a
+# native Linux Docker engine with network_mode: host.
+STT_LOCAL_URL=http://stt-local:9001
+TTS_LOCAL_URL=http://tts-local:9002
+AUDIO_BASE_URL=http://voice-app:3000
+PIPER_VOICE=en_US-lessac-medium
+WHISPER_MODEL=small
+
+# ---- cloud mode settings (only needed if STT_MODE/TTS_MODE=cloud) ----
+# ELEVENLABS_API_KEY=your-elevenlabs-api-key
+# ELEVENLABS_VOICE_ID=your-default-voice-id
+# OPENAI_API_KEY=your-openai-api-key
+
+# ====================================
+# Application Settings
+# ====================================
+
+# HTTP server port for API and audio file serving
+HTTP_PORT=3000
+
+# WebSocket port for audio streaming from FreeSWITCH
+WS_PORT=3001
+
+# Audio files directory
+AUDIO_DIR=/app/audio
+
+# ====================================
+# Outbound Call Settings
+# ====================================
+
+# Maximum conversation turns for outbound calls
+MAX_CONVERSATION_TURNS=10
+
+# Ring timeout in seconds
+OUTBOUND_RING_TIMEOUT=30
+
+# ====================================
+# Optional: Debug
+# ====================================
+
+# DEBUG=voice-app:*

package/Dockerfile

@@ -0,0 +1,84 @@
+# claude-phone-local - single image containing all five services.
+#
+# Layout:
+#   FreeSWITCH  : from the drachtio MRF base image (already compiled)
+#   drachtio    : binary lifted from the official drachtio-server image
+#   Node 20     : copied from node:20-slim into /opt/node
+#   Python venv : /opt/venv with faster-whisper (STT) + piper-tts (TTS)
+#   supervisord : runs all five as one container
+#
+# All persistent state lives in /data (voices, models, audio, config) so a
+# `docker compose down && up` never re-downloads anything.
+
+FROM drachtio/drachtio-server AS drachtio
+FROM node:20-slim AS nodesrc
+
+FROM drachtio/drachtio-freeswitch-mrf
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# drachtio needs these boost/tcmalloc libs, which the FreeSWITCH image lacks.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      libboost-thread1.74.0 \
+      libboost-log1.74.0 \
+      libboost-filesystem1.74.0 \
+      libgoogle-perftools4 \
+      python3 python3-venv \
+      supervisor curl ca-certificates ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=drachtio /usr/local/bin/drachtio /usr/local/bin/drachtio
+# drachtio refuses to start without its config file, even when every setting
+# is supplied on the command line.
+COPY --from=drachtio /etc/drachtio.conf.xml /etc/drachtio.conf.xml
+RUN ldd /usr/local/bin/drachtio | grep "not found" && exit 1 || echo "drachtio libs OK"
+
+# Node into /opt/node so it cannot collide with /usr/local/freeswitch
+COPY --from=nodesrc /usr/local/bin/node /opt/node/bin/node
+COPY --from=nodesrc /usr/local/lib/node_modules /opt/node/lib/node_modules
+RUN ln -sf /opt/node/bin/node /usr/bin/node \
+ && ln -sf /opt/node/lib/node_modules/npm/bin/npm-cli.js /usr/bin/npm \
+ && node --version && npm --version
+
+# Python services
+RUN python3 -m venv /opt/venv \
+ && /opt/venv/bin/pip install --no-cache-dir --upgrade pip \
+ && /opt/venv/bin/pip install --no-cache-dir \
+      fastapi "uvicorn[standard]" python-multipart faster-whisper piper-tts
+# piper CLI must be on PATH for the TTS sidecar to shell out to it
+RUN ln -sf /opt/venv/bin/piper /usr/bin/piper
+
+COPY stt-local/server.py /opt/stt/server.py
+COPY tts-local/server.py /opt/tts/server.py
+
+# Node app (deps first for layer caching)
+WORKDIR /app
+COPY voice-app/package*.json ./
+RUN npm install --omit=dev
+COPY voice-app/ ./
+
+# FreeSWITCH NAT fixes, carried over from the old compose file.
+#  - apply-nat-acl "nat.auto" treats 172.16/12 as local. The LAN (172.16.x) and
+#    the Docker bridge (172.18.x) both fall in that range, so FreeSWITCH decided
+#    the 3CX SBC was local and skipped external-IP substitution, putting the
+#    container IP in the SDP and breaking RTP in both directions.
+#  - local-network-acl "none" stops any further "this peer is local" guessing.
+RUN sed -i '/apply-nat-acl/d' /usr/local/freeswitch/conf/sip_profiles/mrf.xml  && sed -i '/<param name="ext-sip-ip"/a\      <param name="local-network-acl" value="none"/>'       /usr/local/freeswitch/conf/sip_profiles/mrf.xml  && grep -q 'local-network-acl' /usr/local/freeswitch/conf/sip_profiles/mrf.xml  && echo "mrf.xml NAT patches applied"
+
+COPY docker/supervisord.conf /etc/supervisor/supervisord.conf
+COPY docker/entrypoint.sh /usr/local/bin/claude-phone-entrypoint
+# Windows checkouts can introduce CRLF, which makes the shebang "bash
+# and the container restart-loops. Normalise before making it executable.
+RUN tr -d '
+
+# voice-app writes generated audio here and reads devices.json from here
+ENV AUDIO_DIR=/data/audio \
+    PIPER_VOICES_DIR=/data/voices \
+    HF_HOME=/data/models/huggingface \
+    DEVICES_CONFIG=/data/config/devices.json
+RUN rm -rf /app/config && ln -s /data/config /app/config \
+ && rm -rf /app/audio && ln -s /data/audio /app/audio
+
+EXPOSE 3000 3001 5070/udp 5070/tcp 5080/udp 5080/tcp 30000-30100/udp
+
+ENTRYPOINT ["/usr/local/bin/claude-phone-entrypoint"]

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Original work Copyright (c) NetworkChuck (https://github.com/theNetworkChuck/claude-phone)
+Modified work Copyright (c) 2025 Deepak Chougale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Claude Phone" width="200">
+</p>
+
+# Claude Phone (Local)
+
+Voice interface for Claude Code via SIP/3CX. Call your AI, and your AI can call you.
+
+> **Based on [theNetworkChuck/claude-phone](https://github.com/theNetworkChuck/claude-phone).**
+> This is a modified fork of NetworkChuck's original project. All credit for the
+> original design and implementation goes to him — see [Credits](#credits).
+>
+> **What this fork changes:** speech runs fully offline (faster-whisper + Piper
+> instead of OpenAI Whisper and ElevenLabs, so no API keys), English/Hindi/Marathi
+> with automatic language detection, barge-in so you can interrupt mid-sentence,
+> an MCP server so Claude can phone *you*, and the whole stack in a **single
+> Docker container** with a persistent `./data` volume.
+
+## What is this?
+
+Claude Phone gives your Claude Code installation a phone number:
+
+- **Inbound** — call an extension and talk to Claude. Ask it to check your PC,
+  run commands, or answer questions. It has real shell access to the host.
+- **Outbound** — Claude can call *you* when it needs a decision, then talk it
+  through. Available over HTTP or as an [MCP tool](docs/MCP-SERVER.md).
+
+Everything speech-related is **local and free**. The only paid piece is the
+Claude Code CLI itself.
+
+## Prerequisites
+
+Manual, one time:
+
+- **Docker Desktop** (WSL2 backend on Windows)
+- **Claude Code CLI**, logged in — `claude --version`
+- **Node.js 18+** on the host, for `claude-api-server`
+- A **SIP extension** on 3CX (or any SIP PBX)
+
+Everything else — speech models, voices, device config — is downloaded and
+generated automatically on first run.
+
+## Quick start
+
+```bash
+git clone <your-fork> claude-phone-local
+cd claude-phone-local
+cp .env.example .env
+```
+
+Edit `.env` — the three that matter:
+
+```bash
+EXTERNAL_IP=172.16.14.225      # this PC's LAN IP (ipconfig / ip addr)
+SIP_REGISTRAR=172.16.14.225    # your LOCAL 3CX SBC, not the cloud domain
+SIP_EXTENSION=17512            # plus SIP_AUTH_ID and SIP_PASSWORD
+```
+
+Start it:
+
+```bash
+docker compose up -d --build          # first run downloads ~2GB of models
+docker compose logs -f                # watch the bootstrap
+```
+
+In a second terminal, start the host-side Claude wrapper:
+
+```bash
+cd claude-api-server
+CLAUDE_MODEL=claude-sonnet-5 node server.js
+```
+
+When you see this, call your extension:
+
+```
+[MULTI-REGISTRAR] Maya SUCCESS - Registered as ext 17512
+```
+
+## Architecture
+
+One container, one host process:
+
+```
+Phone → 3CX cloud → 3CX SBC (HOST :5060)
+                      │
+        ┌─────────────▼───────────────────────────┐
+        │  claude-phone container                 │
+        │  drachtio · FreeSWITCH · voice-app      │
+        │  faster-whisper · Piper                 │
+        └─────────────┬───────────────────────────┘
+                      │ host.docker.internal:3333
+                      ▼
+        claude-api-server (HOST) → claude.exe (HOST)
+```
+
+Inside the container everything talks over `127.0.0.1`. Persistent state lives
+in `./data` — models, voices and config survive `docker compose down`.
+
+See [CLAUDE.md](CLAUDE.md) for the full architecture and design decisions.
+
+## Languages
+
+English, Hindi and Marathi, detected per utterance — switch language mid-call
+and she follows, replying in the same language with a matching voice.
+
+```bash
+STT_LANGUAGE=auto
+SUPPORTED_LANGS=en,hi,mr
+```
+
+Details and the accuracy/speed trade-off: [docs/LANGUAGES.md](docs/LANGUAGES.md).
+
+## Talking to her
+
+- **Interrupt any time.** Start speaking and she stops — no waiting for her to
+  finish.
+- **Hang up by saying so:** "goodbye", "bye", "end call", "close the call",
+  "बंद करो", "ठेवतो".
+- **One session per call.** The whole call is a single Claude conversation, so
+  she remembers what you said two questions ago.
+- **She fills the silence** with a soft hold tone and the occasional spoken
+  line while she works, instead of going dead.
+
+## Claude calling you
+
+Register the [MCP server](docs/MCP-SERVER.md) and ask in plain language:
+
+> "Run the migration and call me if anything needs a decision."
+
+```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
+```
+
+## Configuration
+
+Common knobs in `.env`:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `EXTERNAL_IP` | — | This PC's LAN IP, for RTP |
+| `WHISPER_MODEL` | `medium` | `small` is ~3x faster, weaker on Marathi |
+| `STT_LANGUAGE` | `auto` | Or pin `en` / `hi` / `mr` |
+| `CLAUDE_TIMEOUT` | `180` | Seconds before giving up |
+| `VAD_NOISE_MULT` | `2.5` | How far above the noise floor counts as speech |
+| `BARGE_MULT` | `1.6` | How hard it is to interrupt her |
+| `PHONE_ENABLE_MCP` | off | Give the phone agent your MCP tools (slower) |
+
+## API endpoints
+
+**voice-app (3000)**
+
+| Method | Endpoint | Purpose |
+|---|---|---|
+| POST | `/api/outbound-call` | Start an outbound call |
+| GET | `/api/call/:id` | Call status |
+| POST | `/api/call/:id/hangup` | End a call |
+| GET | `/api/devices` | List configured devices |
+
+**claude-api-server (3333, host)**
+
+| Method | Endpoint | Purpose |
+|---|---|---|
+| POST | `/ask` | Send a prompt |
+| GET | `/health` | Health check |
+
+## Security
+
+`claude-api-server` runs the CLI with `--dangerously-skip-permissions`. That
+means **no prompts, all tools, full access to this PC as your user**, with your
+normal `~/.claude` config. Anyone who can reach port 3333 can run commands as
+you — keep it bound to localhost.
+
+Never commit `data/config/devices.json` or `.env`; both are gitignored, and a
+`prepublishOnly` guard blocks publishing if they would ship.
+
+## Troubleshooting
+
+```bash
+docker compose logs -f
+docker logs claude-phone 2>&1 | grep -Ei "CALL |error|503"
+curl http://127.0.0.1:3333/health
+```
+
+Straight to voicemail, connected-but-silent, slow answers, restart loops and
+more: **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)**.
+
+## Documentation
+
+- [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
+- [docs/MCP-SERVER.md](docs/MCP-SERVER.md) — letting Claude call you
+- [README-LOCAL-MODE.md](README-LOCAL-MODE.md) — Windows + 3CX specifics
+- [voice-app/README-OUTBOUND.md](voice-app/README-OUTBOUND.md) — outbound API
+- [voice-app/DEPLOYMENT.md](voice-app/DEPLOYMENT.md) — production notes
+- [cli/README.md](cli/README.md) — CLI reference
+
+## License
+
+MIT — same as the original project.
+
+## Credits
+
+This project is a fork of **[claude-phone by NetworkChuck](https://github.com/theNetworkChuck/claude-phone)**
+(`https://github.com/theNetworkChuck/claude-phone.git`). The original concept,
+SIP/3CX integration and conversation design are his work — this fork only adapts
+it for fully-offline speech and multilingual use.
+
+If you find this useful, go support the original:
+
+- Original repository: <https://github.com/theNetworkChuck/claude-phone>
+- NetworkChuck on YouTube: <https://www.youtube.com/@NetworkChuck>
+
+### Changes in this fork
+
+| Area | Original | This fork |
+|------|----------|-----------|
+| STT | OpenAI Whisper API (key required) | faster-whisper, local (no key) |
+| TTS | ElevenLabs API (key required) | Piper, local (no key) |
+| Languages | English | English, Hindi, Marathi (auto-detected) |
+| Containers | Multiple services | Single container via supervisord |
+| Persistence | — | `./data` volume; models survive restarts |
+| Setup | Manual model/config steps | Automated on first run |
+| Conversation | Wait for her to finish | Barge-in — interrupt any time |
+| Outbound | HTTP API | HTTP API + MCP server |
+
+Cloud STT/TTS remain available as an opt-in (`STT_MODE=cloud` / `TTS_MODE=cloud`)
+for anyone who prefers the original behaviour.