mohitbadwal/ringback

> **Your AI agent can call your phone — and actually talk to you.**
**ringback** gives an LLM (Claude, or any MCP client) tools to **reach you on your phone** — from a one-way "fierce" alert all the way to a **live, interruptible voice conversation** — using only free, self-hosted pieces. No paid telephony. No extra API key for the conversation: the model already driving the MCP *is* the voice on the line.
**Highlights**
- 📞 **Two-way voice calls** — the agent rings your phone, you talk, it transcribes you and replies in speech. **Barge-in**: talk over it and it stops.
- 🔔 **Tiered alerts** — a loud push (ntfy / Pushover) or a real SIP ring + chat message, fired only when *the LLM* judges it urgent.
- 🆓 **Free & self-hosted** — pjsua2 + whisper.cpp + Piper neural TTS + a free Linphone SIP account. No Twilio, no per-minute fees.
- 🧠 **No conversation API key** — the calling model is the brain; these tools are just its ears and mouth.
It ships two MCP servers, ringback-alert and ringback-voice:
> **Platform:** macOS, **Linux**, and **Windows** (via WSL2 or Docker). TTS is Piper by default (same voice everywhere), falling back to the OS-native voice (say on macOS). The engine is **headless** — it never opens a local mic/speaker (all audio is WAV ↔ SIP/RTP), so no sound card is required. Setup guides: macOS · Linux · Windows · Docker.
| Server | Tools | What it does |
|---|---|---|
| **ringback-alert** | alert_me, alert_test, alert_status | Fire-and-forget notification: a loud push (ntfy / Pushover) and/or a SIP ring + chat message. |
| **ringback-voice** | call_start, converse, get_conversation, call_end, … | A real **two-way phone conversation**. Rings your phone; you talk, it transcribes you, the LLM replies in speech. Supports **barge-in** (talk over it and it stops). |
The criteria for *when* to contact you live in the tool descriptions — the calling LLM decides. These servers are just the mechanism.
What a call looks like
The LLM calls call_start once, then converse(...) for each turn. Plain alerts are even simpler: one alert_me(...) call.
---
Install as a Claude Code plugin (Docker — one command)
If you have **Docker** and a free Linphone account, this is the fastest path — no local build:
Claude Code prompts for your SIP details (and optional alert backends), stores secrets in your OS keychain, and registers both ringback-voice and ringback-alert plus the watchdog skill. The engine runs in the prebuilt image (pulled on first call). See plugin/README.md.
> Prefer no Docker, or want the native build? Use the paste-prompt below or the manual steps.
Let Claude Code install it for you
🤖 Easiest path: **copy the prompt below and paste it into Claude Code** — it'll clone, build, configure, and register everything, asking you only for what it needs (a free SIP account + your phone to answer a test call).
Prefer to do it by hand? Quick start and the full walkthrough are below.
---
Quick start
Full walkthrough + env-var reference: **Set up ringback-voice** below.
---
Honest caveats (read first)
- **Cross-platform.** macOS (native), Linux (native), Windows (via WSL2 or Docker). The engine is headless — no sound card needed. Native Windows (MSVC) is intentionally not supported; WSL2/Docker is the Windows path.
- **Not ChatGPT-realtime.** The voice loop is record → whisper STT → LLM → Piper/say TTS, so expect **~1–2 s per turn**. It's a reliable walkie-talkie with barge-in, not a streaming realtime voice.
- **The voice feature depends on GPL software** (pjproject/pjsua2). This repo is Apache-2.0, but redistributing a bundle that links pjsua2 carries GPL obligations — see NOTICE. The ringback-alert server is unaffected.
- **Your machine must be awake and online**, and for a voice call a Claude session must be live (it's the brain) for the duration.