055 Architecture C8b42f42

# VoiceMode Connect Architecture

How agents and clients connect through voicemode.dev.

## Overview

```
┌─────────────────┐              ┌─────────────────┐
│   AI Agent      │              │     Client      │
│  (Claude Code)  │              │  (iOS/Web App)  │
└────────┬────────┘              └────────┬────────┘
         │ MCP                            │ WebSocket
         │                                │
         └────────────┬───────────────────┘
                      │
              ┌───────┴───────┐
              │ voicemode.dev │
              │   Platform    │
              └───────────────┘
```

## Components

### Agents

AI assistants that want to have voice conversations. They connect via MCP (Model Context Protocol) and use tools like `status` and `converse`.

- Connect using `mcp-remote` to `https://voicemode.dev/mcp`
- Authenticate via OAuth
- Call MCP tools to interact with the platform

### Clients

Devices that handle the actual voice I/O (microphone/speaker). They connect via WebSocket.

- iOS app - native mobile client
- Web app - browser-based dashboard at voicemode.dev
- Future: macOS menu bar app, browser extension

### Local MCP Server

The local VoiceMode MCP server can also connect to voicemode.dev to monitor remote devices. This provides device visibility without requiring the remote MCP server.

Two connection methods are available:

- **Standalone standby process** (`voicemode connect standby`) - a long-running CLI process that listens for wake signals and starts agents
- **In-process WebSocket client** - a background connection within the MCP server that tracks connected devices (opt-in via `VOICEMODE_CONNECT_AUTO=true`)

The in-process client is disabled by default. VoiceMode does not connect to external services without explicit user opt-in.

### Platform

The voicemode.dev backend routes messages between agents and clients.

- User accounts link agents and clients
- WebSocket connections for real-time voice delivery
- OAuth authentication via Auth0

## Connection Flow

1. **Agent connects**: Claude Code adds the MCP server and authenticates
2. **Client connects**: User opens iOS/web app and signs in with same account
3. **Agent sends message**: Uses `converse` tool with text to speak
4. **Platform routes**: Message delivered to connected client(s)
5. **Client speaks**: TTS plays on device, STT captures response
6. **Response returns**: User's voice response sent back to agent

## Authentication

Both agents and clients authenticate against the same voicemode.dev account:

- **Agents**: OAuth flow triggered when MCP tools are first used
- **Clients**: Standard login flow in app/web

The platform matches agents to clients by user account.

## Protocol Notes

- MCP transport: stdio to mcp-remote, which handles HTTP/SSE
- WebSocket: persistent connection for clients
- Voice data: handled by clients, not transmitted through platform (clients use their own TTS/STT)

## See Also

- [MCP Protocol](https://modelcontextprotocol.io/) - Model Context Protocol specification
- [Auth0](https://auth0.com/) - Authentication provider