LivePulse

English | 中文

Proactive perception + multi-backend AI agent framework for Apple Silicon. Continuously senses the environment via microphone and camera, intelligently decides when to engage, and delivers streaming voice responses.

How It Works

Mic --> VAD --> ASR --+
                     +--> Context --> Gate --> Agent --> TTS --> Speaker
Cam --> FrameDiff ---+
        VLM ---------+

All perception (VAD, ASR, VLM, gating, TTS) runs locally on Apple Silicon via MLX. Only the agent backend (OpenClaw, Claude, OpenAI) hits a remote API.

Installation

Requires Python 3.11+ and uv.

# Clone and install (development)
git clone https://github.com/solar2ain/LivePulse.git && cd LivePulse
uv pip install -e .

# Run via uv
uv run livepulse --help

For a global livepulse command (no uv run prefix):

uv tool install -e .
livepulse --help

Quick Start

# 1. Interactive setup wizard — configures models, devices, agent, gateway
livepulse onboard

# 2. Start the perception engine
livepulse run

# 3. Connect a dashboard
livepulse tui          # terminal UI
livepulse webui        # browser UI

CLI Overview

Command	Description
livepulse run	Start perception engine (foreground)
livepulse service start/stop/status	Background service lifecycle
livepulse tui	Terminal dashboard (connects to running daemon)
livepulse webui	Browser dashboard
livepulse onboard	Interactive setup wizard
livepulse test vad/asr/tts/aec/trigger/camera	Test individual perception components
livepulse test agent	Test agent backends (chat/openclaw/claude-code)
livepulse test gain	Mic input gain calibration wizard
livepulse test voiceprint	Speaker verification test
livepulse devices list/test	Audio/video hardware management
livepulse voiceprint enroll/list/delete	Speaker verification profiles
livepulse config show/edit/validate	Configuration management
livepulse peers list/approve/revoke	Manage paired remote devices
livepulse claude query/sessions/context	Claude Code session management
livepulse log	View and tail log files

Agent Backends

LivePulse supports multiple agent backends via the AgentBackend abstraction:

• OpenClaw (type: openclaw) — connects to an OpenClaw Agent Runtime via WebSocket
• Chat (type: chat) — direct LLM chat via mlx_lm, OpenAI, or Anthropic APIs
• Claude Code (type: claude) — Claude Code SDK subprocess for coding tasks

Configure agents in livepulse.yaml under the agents: section. Multiple agents can coexist — switch between them using wake words or CLI flags.

Gateway & Security

LivePulse runs a WebSocket gateway so TUI, WebUI, and remote clients can connect to the daemon.

Shared Token (WebUI / local TUI)

Set a shared token in your config (gateway.token). The onboard wizard generates one automatically.

gateway:
  host: "0.0.0.0"    # 0.0.0.0 for remote access, 127.0.0.1 for local only
  port: 19520
  token: "your-secret-token"

Local clients (livepulse tui, livepulse webui) read the token from config automatically.

Device Pairing (remote TUI / mobile apps)

Remote devices (Android, iOS, other machines) use ed25519 device identity for authentication:

# On the host: list pending connection requests
livepulse peers list

# Approve a device
livepulse peers approve <device-id-prefix>

# Revoke access
livepulse peers revoke <device-id-prefix>

Each remote device generates a unique ed25519 keypair. The device ID is derived from the public key (SHA256(pubkey)). Connections are verified by signature on every reconnect.

Remote Access

For accessing LivePulse from outside your local network, use Tailscale (recommended) for NAT traversal and encryption. Bind the gateway to 0.0.0.0, set a token, and connect via your Tailscale IP.

macOS Service

Install LivePulse as a macOS LaunchAgent for background operation:

# Install globally first
uv tool install -e .

# Install launchd service
livepulse service install              # manual start
livepulse service install --login      # auto-start on login

# Manage with launchctl
launchctl load ~/Library/LaunchAgents/com.livepulse.daemon.plist
launchctl unload ~/Library/LaunchAgents/com.livepulse.daemon.plist

# Or use the built-in commands
livepulse service start / stop / status

# Uninstall
livepulse service uninstall

Configuration

Default config template: config/default.yaml. The onboard wizard writes to ~/.livepulse/livepulse.yaml.

Key sections:

• audio — microphone input, VAD thresholds, software input gain, AEC
• asr — speech-to-text (whisper-cli, whisper-server, or mlx_audio)
• vision — camera, frame differencing, VLM
• voiceprint — speaker verification (WeSpeaker)
• trigger — context window, wake words, gate model
• models — reusable model endpoints (mlx_lm, OpenAI, Anthropic)
• agents — agent definitions (openclaw, chat, claude)
• tts — text-to-speech (mlx_audio), filler phrases, error voice
• gateway — WebSocket server (host, port, token)

Tech Stack

• Python — perception engine, CLI, all ML inference
• MLX — Apple Silicon acceleration for ASR, TTS, LLM gating, VLM
• whisper-cpp — speech recognition (via whisper-cli/whisper-server)
• Silero VAD — voice activity detection
• OpenCV — camera capture and frame differencing
• WeSpeaker — speaker verification / voiceprint
• Textual — terminal UI framework
• React — WebUI dashboard
• Flutter — cross-platform native app (macOS, iOS, Android, Windows, Linux, Web)

License

MIT