# vlab

> vlab gives AI coding agents a real voice — spoken audio alerts via xAI Grok or ElevenLabs TTS, exposed as an MCP tool so any agent can audibly surface completions, errors, and status without the user watching a terminal.

vlab runs on macOS Apple Silicon. It uses xAI Grok and/or ElevenLabs for TTS synthesis (with a free offline macOS `say` fallback). Audio plays locally through the system audio device.

## Install

- [Install script](https://vlab.daystra.com/install.sh): one line — `curl -fsSL https://vlab.daystra.com/install.sh | sh`. Installs the `vlab` binary to `~/.local/bin`.
- Store a TTS API key in the macOS Keychain (set at least one). vlab reads these by service name — no env vars, no secrets in dotfiles:
  - `security add-generic-password -s GROK_API_KEY -a "$USER" -w "your-grok-key"`
  - `security add-generic-password -s ELEVENLABS_API_KEY -a "$USER" -w "your-elevenlabs-key"`
  - (Env vars `$GROK_API_KEY` / `$ELEVENLABS_API_KEY` also work.)
- Wire into Claude Code: `vlab install` (registers the global MCP server + installs the agent skill into `~/.claude`).

## MCP — wiring vlab into an AI coding agent

Easiest: `vlab install`. Or add to `.mcp.json` in your project:
```json
{ "mcpServers": { "vlab": { "command": "vlab", "args": ["mcp-server"] } } }
```

- **Global MCP server**: `vlab mcp-server` — start once; connects to any MCP client (Claude Code, Cursor, Windsurf).
- **MCP tool `speak`**: agents call `vlab__speak` with a `text` argument. vlab synthesizes via Grok or ElevenLabs and plays audio. Optional args: `type`, `persona`, `mood`, `snark` (0–10), `project`.

## Voices & personas

- Grok voices: `rex`, `ara`, `leo`, `eve`, `sal`. ElevenLabs: `veda`, `alfred`. Select per-call (`--persona rex`) or set a global default.

## CLI commands

- `vlab speak "<text>"` — speak text immediately (Grok or ElevenLabs + system audio)
- `vlab say "<text>"` — alias for speak
- `vlab mute` / `vlab stop` — silence output until unmuted / stop the current utterance
- `vlab install` — wire the MCP server + skill into Claude Code
- `vlab update` — upgrade vlab to the latest published release
- `vlab voices [--search <q>]` — list available voices or search the ElevenLabs library
- `vlab usage` — this month's TTS character spend
- `vlab doctor` — verify Grok/ElevenLabs keys, audio device, and config
- `vlab mcp-server` — start the MCP server (used by `.mcp.json` auto-discovery)
- `vlab --version` — print installed version

## When to use vlab

- "Alert me when a long build finishes" → agent calls `vlab__speak("Build complete.")`.
- "Tell me out loud if tests fail" → agent calls `vlab__speak("Tests failed. Check the output.", type="error")`.
- "Notify me when you need input" → agent calls `vlab__speak("I need a decision from you.", type="question")`.
- "Stop speaking" → `vlab stop` or `vlab mute` from any terminal.

## Machine-readable

- [Agent manifest](https://vlab.daystra.com/.well-known/vlab.json): name, install, MCP server + tools, commands, links.
- [Latest release](https://vlab.daystra.com/latest.json): current version and target.
- [Install script](https://vlab.daystra.com/install.sh): POSIX shell installer, macOS aarch64 only.