ringback

Purpose

ringback lets an LLM (such as Claude or any MCP client) contact you by phone: from one-way "emergency" alerts to two-way voice conversations with real-time interruptions. It uses only free, self-hosted components, does not depend on paid telephony services, and does not require an extra API key for conversations—the model already driving MCP is the voice on the other end of the line.

Key Capabilities

• Two-way voice calls: The agent calls your phone, you speak, it transcribes your speech and replies with voice. Supports barge-in: when you interrupt, it stops immediately.
• Tiered alerts: Push via ntfy / Pushover, or a real SIP ring plus chat message, triggered only when the LLM judges it urgent.
• Free and self-hosted: pjsua2 + whisper.cpp + Piper neural TTS + a free Linphone SIP account. No Twilio, no per-minute billing.
• No conversation API key needed: The calling model is the brain; these tools are just its ears and mouth.

It provides two MCP servers:ringback-alert and ringback-voice.

Platforms and How It Runs

Supports macOS, Linux, and Windows (via WSL2 or Docker). TTS uses Piper by default (consistent voice across platforms), falling back to the operating system's native voice (on macOS, say). The engine is headless—it never opens a local microphone/speaker (all audio is WAV ↔ SIP/RTP), so no sound card is needed. Native Windows (MSVC) is intentionally unsupported; the Windows path is WSL2/Docker.

Usage

Install as a Claude Code plugin (Docker, one command)

If you have Docker and a free Linphone account, this is the fastest path and requires no local build. Claude Code will prompt you for SIP information (and optionally an alert backend), store the secrets in the operating system keychain, and register ringback-voice、ringback-alert as well as the watchdog skill. The engine runs in a prebuilt image (pulled on first call).

Let Claude Code install it for you

Copy the prompt and paste it into Claude Code; it will clone, build, configure, and register everything, asking you only for the necessary information (a free SIP account + your phone to answer a test call).

Manual installation prerequisites

• macOS (Apple Silicon or Intel) with Homebrew—run ./setup.sh
• Linux (Debian/Ubuntu/Fedora)—run ./setup-linux.sh
• Windows—WSL2 (run ./setup-linux.shinside it) or Docker Desktop
• Any system with Docker—docker build -t ringback .
• A free Linphone SIP account (sip.linphone.org) and the Linphone iOS/Android app
• Python 3.10+

Set up ringback-voice (4 steps)

1. Clone and install:setup.sh installs the toolchain, compiles pjsua2 from source (about 20–30 minutes), relinks the pjproject dynamic library, downloads the whisper model, installs Piper and voices, installs dependencies, and creates voice.env. Safe to run repeatedly. On Linux use ./setup-linux.sh.
2. Get a free SIP account: register at https://subscribe.linphone.org , get a username and password, with the address sip:<username>@sip.linphone.org. Install the Linphone app on your iPhone and log in; confirm it shows Connected.
3. Fill in voice.env(created by setup.sh; just edit it). Only three variables are required.
4. Register and test: in a fresh Claude session, say "Use ringback-voice to call me and say hello." Your phone should ring.

Claude Desktop users need to add the configuration in ~/Library/Application Support/Claude/claude_desktop_config.json (absolute paths required; restart the app).

Set up ringback-alert (optional)

ringback-alert Read config from the MCP client's env block (no source file needed). Register it with the channel you want. See alert.env.example for all variables (ntfy / Pushover / SIP ringing). Use a long random ntfy topic—anyone who knows it can read/publish.

Using ringback-voice (conversation)

The LLM drives a simple loop:converse(text) listens while speaking, and when you interrupt, it stops immediately and tells the LLM where it got to and what you said (barge-in).get_conversation() returns the full transcript (both sides, including barge-in points). TTS reads it out verbatim, so the tool description instructs the model to only give a plain-language summary and never read out raw logs/code—those are sent as text via alert_me . Whisper model accuracy/speed tradeoff (set WHISPER_MODEL）：base.en(fast/rough) → small.en(balanced, default) → medium.en(most accurate/slow).

Using ringback-alert (notification)

alert_me(message, severity, title), severity = info | warn | critical. Channels are set via ALERT_CHANNEL(comma-separated ntfy, pushover, call):

• ntfy—free push; loud, but cannot break through iOS Focus/Silent unless whitelisted under Focus.
• Pushover—one-time $5; provides true iOS critical alerts at critical level (breaks through Focus/Silent, repeats until acknowledged).
• call—free SIP ringing via baresip + Linphone chat message; full-screen ring, by default only at critical.

A built-in rate limit guard (default 5/60 seconds, per process) prevents accidental triggers from harassing you.

Built-in skill: watchdog

skills/watchdog/ is a ready-to-use Claude skill based on these servers. It watches conditions you specify (CI runs, deployments, pods, files) and only escalates when you have actually left your laptop: chat status → chat warning → ringback-alert push → ringback-voice call—based on input idle time. It never interrupts while you are typing, and de-escalates as soon as you touch the keyboard. Usage:/watchdog <what to watch> | priority=<low|medium|critical>.

When to use

• Let an AI agent proactively call to notify you in urgent situations.
• Automated workflows that need two-way voice confirmation or conversation.
• Monitor CI, deployments, and service status, and escalate alerts in tiers when you are away.

Limitations and caveats

• Not ChatGPT real-time voice: the voice loop is record → whisper STT → LLM → Piper/say TTS, about 1–2 seconds per turn. It is reliable walkie-talkie with barge-in, not streaming real-time voice.
• Voice functionality depends on GPL software (pjproject/pjsua2). This repository is Apache-2.0, but redistributing a bundle linked against pjsua2 carries GPL obligations—see NOTICE.ringback-alert server is unaffected.
• Your machine must stay awake and online, and there must be an active Claude session during the voice call (it is the brain).
• Barge-in assumes low echo (handset or headset). On speakerphone, TTS may feed back into the microphone and falsely trigger "barge-in". There is no echo cancellation on this path.
• iOS push reality: self-hosted/free push cannot truly break through an iPhone's Focus/Silent unless via Pushover critical alerts (paid).
• Security: SIP credentials are stored only locally and are gitignored voice.env(as well as the baresip account file for ringback-alert), and never put them into a repository or MCP client configuration. The voice server will only dial the single SIP URI you configure and cannot dial arbitrary numbers. Treat the ntfy topic as confidential (use a long random topic); do not put sensitive details in the alert body on the public ntfy.sh.

License

Apache-2.0 (see LICENSE), the pjproject dependency of the voice component has important GPL considerations—see NOTICE. Built on pjproject/pjsua2, whisper.cpp, baresip, ntfy and Linphone.