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.

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

agent → call_start("Your nightly deploy failed — want me to walk you through it?")
   📞 your phone rings; you pick up and hear the line
you   → "yeah, which step broke?"
agent → "The database migration. I can roll it back and retry — want that?"
you   → "yes, do it"            ← you can also just talk over the agent to interrupt
agent → call_end()

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:

/plugin marketplace add mohitbadwal/ringback
/plugin install ringback@ringback

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).

Set up the ringback MCP server for me — it lets you (the agent) call my phone when you
need a decision while I'm away. Repo: https://github.com/mohitbadwal/ringback
(runs on macOS, Linux, or Windows via WSL2/Docker).

Please:
1. Detect my OS and pick the path:
   - macOS                 → ./setup.sh (Homebrew); read docs/SETUP_MACOS.md
   - Linux or Windows-WSL2 → ./setup-linux.sh; read docs/SETUP_LINUX.md
   - Windows without WSL2   → use Docker; read docs/SETUP_DOCKER.md
2. Clone https://github.com/mohitbadwal/ringback, cd in, and read the README + the doc above.
3. Run the setup for my OS (compiles pjsua2 from source — ~20–30 min — installs whisper +
   Piper TTS, downloads models, and creates voice.env).
4. I need a free Linphone SIP account (the phone line): walk me through signing up at
   https://subscribe.linphone.org and installing the Linphone app on my phone, then put my
   SIP id/username/password into voice.env (and set VOICE_DISPLAY_NAME to a caller-ID name).
5. Register it (per OS):
   - macOS:      claude mcp add ringback-voice --scope user -- "$PWD/run_voice_mcp.sh"
   - Linux/WSL2: claude mcp add ringback-voice --scope user -- python3 "$PWD/run_voice_mcp.py"
   - Docker:     see docs/SETUP_DOCKER.md (build image, convert creds to voice.docker.env, then register a `docker run -i` command)
6. macOS only: if a test call fails with error -32000 or a segfault, run ./fix_macos_twolevel.sh.
7. Tell me to start a fresh session, then call me to confirm two-way voice works.

Ask me whenever you need input (SIP credentials, my phone to answer the test call, etc.).

Prefer to do it by hand? Quick start and the full walkthrough are below.

Quick start

git clone https://github.com/mohitbadwal/ringback && cd ringback
./setup.sh        # installs EVERYTHING (toolchain, pjsua2, whisper model, deps) + creates voice.env
# edit voice.env → add your 3 SIP vars (free account: https://subscribe.linphone.org), then:
claude mcp add ringback-voice --scope user -- "$PWD/run_voice_mcp.sh"

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.
• Barge-in assumes low acoustic echo (handset or headset). On speakerphone, the TTS can echo into the mic and false-trigger "interruption." There's no echo cancellation in this path.
• iOS push reality: a self-hosted/free push can't truly pierce Focus/Silent on iPhone except via Pushover's Critical Alerts (paid) — see ringback-alert notes below.

Architecture

  LLM (Claude)  ──MCP tools──▶  ringback-voice server (Python)
                                   │  call_start / converse / listen / speak
                                   ▼
                 pjsua2 (SIP+SRTP, built from source)  ──▶  Linphone SIP server
                   │  Piper/say → ffmpeg → WAV  (speak)        │ APNs VoIP push
                   │  record → whisper.cpp (listen)            ▼
                   └───────────────────────────────────▶  your iPhone rings

ringback-alert is simpler: it shells out to ntfy/Pushover HTTP and/or baresip for a SIP ring + chat message.

Prerequisites

• One of:
  • macOS (Apple Silicon or Intel) with Homebrew — run ./setup.sh
  • Linux (Debian/Ubuntu/Fedora) — run ./setup-linux.sh (see docs/SETUP_LINUX.md)
  • Windows — WSL2 (run ./setup-linux.sh inside it) or Docker Desktop (see docs/SETUP_WINDOWS.md)
  • Any OS with Docker — docker build -t ringback . (see docs/SETUP_DOCKER.md)
• A free Linphone SIP account (sip.linphone.org) and the Linphone iOS/Android app (for the ring/voice features)
• Python 3.10+ (the pjsua2 bindings are built against whichever python3 you point at)

Set up ringback-voice — 4 steps

1. Clone + install everything:

git clone https://github.com/mohitbadwal/ringback && cd ringback
./setup.sh

setup.sh installs the toolchain, compiles pjsua2 from source (~20–30 min — no Homebrew formula exists for the bindings), relinks the pjproject dylibs to a two-level OpenSSL namespace (the macOS fix that makes SIP/SRTP work), downloads the whisper model, installs Piper + a voice, installs deps, and creates voice.env for you. Safe to re-run. (Override PYTHON_BIN / PJPROJECT_DIR / WHISPER_MODEL_NAME if your layout differs.)

On Linux? Use ./setup-linux.sh instead — it does the same build with apt/dnf and needs no OpenSSL relink. On Windows? Use WSL2 (docs/SETUP_WINDOWS.md) or Docker. Register the server with the cross-platform launcher python3 run_voice_mcp.py (the .sh is macOS-only).

Hit a snag on macOS? docs/SETUP_MACOS.md is a field-tested root-cause + troubleshooting guide (build target, the OpenSSL flat-namespace fix, whisper model, symptom→fix table).