Metadata-Version: 2.4
Name: vib
Version: 0.1.0
Summary: AI agents vibrate/call you when they need input or finish a task
Author: Yusuke Watanabe
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: ai,coding,notification,tts,twilio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: fastmcp>=2.0; extra == 'all'
Requires-Dist: gtts; extra == 'all'
Requires-Dist: pyttsx3; extra == 'all'
Requires-Dist: websockets>=12.0; extra == 'all'
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.0; extra == 'mcp'
Provides-Extra: speaker
Requires-Dist: websockets>=12.0; extra == 'speaker'
Provides-Extra: tts
Requires-Dist: gtts; extra == 'tts'
Requires-Dist: pyttsx3; extra == 'tts'
Description-Content-Type: text/markdown

# vib

**AI agents call you when they need attention.**

[![PyPI](https://img.shields.io/pypi/v/vib.svg)](https://pypi.org/project/vib/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:

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

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

## Quick Start

```bash
pip install vib
```

### Option 1: MCP Server (for Claude Code)

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

```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

```python
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

```bash
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:

```bash
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.

```bash
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:

```bash
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

```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

```bash
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](LICENSE)
