Labsco
mohitbadwal logo

Ringback

★ 15

from mohitbadwal

Enables AI agents to initiate two-way voice calls and send tiered alerts to your phone using self-hosted, free telephony solutions.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#browser#database#voice#devops#git#security#video-editing

ringback

License Platform MCP Install with Claude Code

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.

ServerToolsWhat it does
ringback-alertalert_me, alert_test, alert_statusFire-and-forget notification: a loud push (ntfy / Pushover) and/or a SIP ring + chat message.
ringback-voicecall_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

Copy & paste — that's it
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.

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

Copy & paste — that's it
  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.

Using ringback-voice (the conversation)

The LLM drives a simple loop:

Copy & paste — that's it
reply = call_start("Hi, it's your assistant — your deploy failed. Want details?")
# rings the phone, speaks the line, returns the user's first words
reply = converse("It failed on the database migration step. Want me to retry it?")
# speaks AND listens in one interruptible turn
... repeat converse() each turn ...
call_end()   # when the user says "bye" / hangs up
  • converse(text) speaks while listening. If you talk over it, it stops immediately and tells the LLM how far it got and what you said (barge-in).
  • get_conversation() returns the full transcript so far — both sides, plus where it got interrupted.
  • TTS reads text literally, so the tool descriptions instruct the model to speak plain-language summaries, never raw logs/codes — those go via alert_me as text instead.

Whisper model accuracy/speed trade-off (set WHISPER_MODEL): base.en (fast/rough) → small.en (balanced, default) → medium.en (most accurate/slow).

Using ringback-alert (notifications)

alert_me(message, severity, title) with severity = info | warn | critical. Channels via ALERT_CHANNEL (comma list of ntfy, pushover, call):

  • ntfy — free push; loud but does not pierce iOS Focus/Silent unless whitelisted per-Focus.
  • Pushover — $5 one-time; true iOS Critical Alerts (pierces Focus/Silent, repeats until acknowledged) at critical.
  • call — free SIP ring + Linphone chat message via baresip; rings full-screen, only at critical by default.

A built-in rate-limit guard (default 5/60s, per-process) stops a misfiring caller from spamming you.

Bundled skill: watchdog

skills/watchdog/ is a ready-to-use Claude skill built on these servers. It watches a condition you give it (a CI run, a deploy, a pod, a file) and escalates only when you're actually away from the laptop — chat status → chat warning → ringback-alert push → ringback-voice call — judged by input-idle time (macOS, Linux, or Windows; see platform_compat.hid_idle_seconds). It never interrupts you while you're typing, and de-escalates the moment you touch the keyboard.

Copy & paste — that's it
cp -r skills/watchdog ~/.claude/skills/watchdog   # install for Claude Code

Then: /watchdog <what to watch> | priority=<low|medium|critical> — low = chat only, medium = may send a phone alert, critical = may place a call. Full design in skills/watchdog/SKILL.md.

Security

  • SIP credentials live only in your local, gitignored voice.env (and the baresip accounts file for ringback-alert) — never in the repo or the MCP client config when you can avoid it.
  • The voice server only ever calls the single SIP URI you configure — it cannot dial arbitrary numbers.
  • Treat ntfy topics as secrets (use a long random topic); don't put sensitive detail in alert bodies on public ntfy.sh.
  • See NOTICE for the GPL/pjproject licensing caveat before redistributing.

License

Apache-2.0 (see LICENSE), with an important GPL caveat for the voice component's pjproject dependency — see NOTICE.

Credits

Built on pjproject/pjsua2, whisper.cpp, baresip, ntfy, and Linphone.