vib

AI agents call you when they need attention.

vib lets your AI coding agents notify you via phone call, SMS, email, or local speaker -- so you can sleep, walk away, or focus on other work while they code.

You: "Refactor the auth module, call me when done."
Claude: *works for 45 minutes*
Your phone rings: "Refactoring complete. All 47 tests pass."

Why vib?

AI coding agents (Claude Code, Cursor, Copilot) can work autonomously for long periods. But they get stuck, need decisions, or finish tasks -- and you have no idea unless you're staring at the terminal.

vib solves this with one line:

vib.call("I need your input on the database schema")

Your phone rings. You answer. You're back in the loop.

Quick Start

pip install vib

Option 1: MCP Server (for Claude Code)

The simplest setup. Add to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "vib": {
      "command": "vib-mcp",
      "env": {
        "VIB_API_KEY": "your_api_key",
        "VIB_URL": "https://vibcode.io",
        "VIB_CALL": "+1234567890",
        "VIB_SMS": "+1234567890",
        "VIB_EMAIL": "you@example.com",
        "VIB_SPEAKER": "bedroom"
      }
    }
  }
}

Only set the channels you want. Omit the rest.

Now Claude Code has access to:

• notify(message) -- sends to all your configured channels
• call_me(message) -- phone call
• send_sms(message) -- text message
• send_email(message) -- email
• speak(message) -- play through connected speakers

Option 2: Python Library

import vib

vib.call("Build finished")              # phone call via Twilio
vib.sms("Deploy complete")              # SMS via Twilio
vib.email("Results ready")              # email via SMTP
vib.speak("Task completed")             # local text-to-speech

Option 3: REST API

curl -X POST https://vibcode.io/api/send/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "call", "message": "Build done", "to": "+1234567890"}'

Notification Channels

Channel	How	Setup
Call	Phone call with TTS	Twilio (shared or BYO)
SMS	Text message	Twilio (shared or BYO)
Email	SMTP email	Gmail app password or any SMTP
Speaker	Local TTS via WebSocket	vib-speaker daemon

Speaker Daemon

Register a named speaker that plays notifications through your local audio:

pip install vib[speaker]
VIB_API_KEY=your_api_key vib-speaker --name bedroom

The speaker connects via WebSocket and stays running. When any agent sends a speak notification, all your connected speakers play it. Auto-reconnects on disconnect.

Multiple speakers supported: bedroom, office, lab -- each plays independently.

Self-Hosted Dashboard

vib includes a web dashboard for managing your account, API keys, and notification history.

git clone https://github.com/ywatanabe1989/vib && cd vib
cp service/.env.example service/.env    # add your Twilio creds
make run                                # http://localhost:8742

Or with Docker:

cd service && docker compose up --build  # http://localhost:8742

The dashboard provides:

• Setup -- select notification type and send test notifications
• API -- your API key, MCP config, and curl examples
• Speakers -- connected speakers with online/offline status
• Advanced Settings -- BYO Twilio/SMTP configuration
• History -- log of all sent notifications

API Reference

Python

import vib

# Phone call
result = vib.call("Task completed", to="+1234567890")
# {"success": True, "to": "+1234567890"}

# SMS
result = vib.sms("Deploy done", to="+1234567890")
# {"success": True, "to": "+1234567890", "sid": "SM..."}

# Email
result = vib.email("Results ready", to="you@example.com", subject="vib notification")
# {"success": True, "to": "you@example.com"}

# Speak (local TTS, no recipient needed)
result = vib.speak("Build finished")
# {"success": True, "backend": "pyttsx3"}

REST API

POST /api/send/

Field	Type	Required	Description
type	string	yes	call, sms, email, or speak
message	string	no	Notification text (default: "Your AI agent needs your attention.")
to	string	no	Recipient phone/email (uses configured default)

Headers: Authorization: Bearer <api_key>

MCP Tools

Tool	Description
notify(message)	Send to all configured channels
call_me(message, to?)	Phone call
send_sms(message, to?)	SMS
send_email(message, to?)	Email
speak(message)	Speaker TTS

Configuration

MCP Environment Variables

Variable	Description	Example
VIB_API_KEY	Your API key (required)	vib_xxxx
VIB_URL	Server URL	https://vibcode.io
VIB_CALL	Phone number for calls	+1234567890
VIB_SMS	Phone number for SMS	+1234567890
VIB_EMAIL	Email for notifications	you@example.com
VIB_SPEAKER	Speaker name	bedroom

Service Environment (.env)

Variable	Description
VIB_TWILIO_SID	Twilio Account SID
VIB_TWILIO_TOKEN	Twilio Auth Token
VIB_TWILIO_FROM	Twilio sender number
DJANGO_SECRET_KEY	Django secret key

Phone Number Formats

vib accepts any format and normalizes automatically:

+61412345678       -> +61412345678
+61 0412 345 678   -> +610412345678
0412345678         -> +61412345678  (Australian)
+61-412-345-678    -> +61412345678
6505551234         -> +16505551234  (US)

Architecture

Claude Code / AI Agent
    |
    v
vib-mcp (MCP server)  --->  vib API (Django + Daphne)
                                |
                    +-----------+-----------+
                    |           |           |
                Twilio      SMTP      WebSocket
                (call/sms)  (email)   (speakers)
                                        |
                              +---------+---------+
                              |                   |
                        vib-speaker           vib-speaker
                        "bedroom"             "office"

Components:

• vib -- Python library (pip install vib), zero required dependencies
• vib-mcp -- MCP server for Claude Code integration
• vib-speaker -- WebSocket speaker daemon for local TTS
• service/ -- Django dashboard with user auth, API keys, WebSocket (Daphne/Channels)

Development

make install    # install vib package with all extras
make dev        # run dev server with hot reload
make test       # run tests (24 tests)
make clean      # remove artifacts

License

AGPL-3.0 -- see LICENSE