Skip to content

Docs/windows support #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alabulei1 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Docs/windows support #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ad5bc72
docs: add Windows install and run instructions
alabulei1 Jun 24, 2026
ccc9e6b
docs: restructure README around Whisper-first, keyboard-direct flow
alabulei1 Jun 24, 2026
3f45b55
docs: move API Reference to the end of README and zh doc
alabulei1 Jun 24, 2026
2e4cf95
docs: clarify Vibetty is agent-agnostic with per-agent launch commands
alabulei1 Jun 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 142 additions & 86 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,73 +1,66 @@
# Vibetty

WebSocket terminal server with voice input support and Claude AI intelligent interaction.
Voice-driven terminal for AI coding agents. Speak into a **VibeKeys Max** keyboard and Vibetty transcribes your speech straight into a coding agent like Claude Code, Codex, or Gemini CLI — or any terminal program — served over the web.

## Features
## How it works

- **WebSocket Terminal** - Real-time terminal web interface based on Axum framework
- **Voice Input** - Speech-to-text support for executing commands via voice
- **Claude AI Integration** - AI-assisted terminal interaction using `echokit_terminal`
- **Multiple ASR Support**
- OpenAI Whisper API
- Alibaba Cloud Paraformer real-time speech recognition (todo)
You speak into the VibeKeys Max keyboard's built-in microphone (push-to-talk or toggle). The keyboard streams the audio over a WebSocket to the Vibetty server. In the default **Whisper** mode, the server packages the audio as WAV and sends it to a Whisper-compatible API (Groq, OpenAI, GLM…), then injects the transcribed text into your terminal session and the AI agent running in it. A browser view shows the live terminal.

## Quick Start
```
VibeKeys Max mic ──WebSocket──▶ Vibetty server ──WAV──▶ Whisper API ──text──▶ terminal + agent
(push-to-talk / toggle)
```

### ASR Configuration
Prefer not to use a cloud API? **WebVosk** mode runs speech recognition locally in the browser instead, with no API key. See [WebVosk](#webvosk--offline-no-api-key).

Vibetty supports two speech recognition modes:
## Features

#### Interactive Setup (Recommended)
- **WebSocket Terminal** - Real-time terminal web interface based on the Axum framework
- **Voice Input** - Speak commands through the VibeKeys Max microphone; speech is transcribed to text
- **Agent-agnostic** - wraps any terminal-based coding agent (Claude Code, Codex, Gemini CLI, OpenCode, aider…) or any shell command — Vibetty has no hard dependency on any one agent
- **Multiple ASR Backends**
- Whisper API — OpenAI, Groq, GLM, ByteFuture, or any custom endpoint (default)
- WebVosk — offline, in-browser, no API key
- Alibaba Cloud Paraformer real-time recognition (todo)

Run the setup wizard to configure ASR interactively:
## Installation

```bash
vibetty setup
```

This launches a TUI where you can:
1. Select a platform: **Whisper** or **WebVosk**
2. If Whisper, choose a provider preset: **OpenAI**, **ByteFuture**, **Groq**, **GLM**, or **Custom**
3. Fill in API key and other settings
4. Configuration is saved to `~/.vibetty/config.toml`
### Option A: Download a pre-built binary

#### Manual Configuration
Download the latest release for your platform from the [releases page](https://github.com/second-state/vibetty/releases):

You can also configure ASR manually via environment variables.
| Platform | Asset |
|---|---|
| Linux | `vibetty-linux-x64` |
| macOS (Apple Silicon) | `vibetty-macos-arm64` |
| Windows | `vibetty-windows-x64.exe` |

##### Option 1: Whisper API (Server-side)
### Option B: Build from source

Create a `.env` file and configure the Whisper API (Groq recommended). Alternatively, you can set these environment variables directly in your shell configuration file (e.g., `~/.bashrc` or `~/.zshrc`):
Requires [Rust](https://rustup.rs/).

```bash
VIBECODE_ASR_API_KEY=your_api_key_here
VIBECODE_ASR_URL=https://api.groq.com/openai/v1/audio/transcriptions
VIBECODE_ASR_MODEL=whisper-large-v3
VIBECODE_ASR_LANG=en
VIBECODE_ASR_PROMPT=
cargo build --release
# binary at ./target/release/vibetty (vibetty.exe on Windows)
```

Then start the service:

**Option A: Download pre-built binary**
### Add to your PATH (optional)

Download the latest release from the [releases page](https://github.com/second-state/vibetty/releases):
To run `vibetty` from any directory, place the binary in a directory on your `PATH`. We recommend `~/.cargo/bin`:

```bash
# After downloading
./vibetty -- claude
```

**Option B: Build from source**
# Pre-built binary
mv vibetty ~/.cargo/bin/

```bash
# Build the release binary
cargo build --release
./target/release/vibetty -- claude
# Or self-compiled binary
mv target/release/vibetty ~/.cargo/bin/
```

**Tip:** To run `vibetty` from any directory, place the binary in a directory on your `PATH`. If it exists, we recommend `~/.cargo/bin`:
On Windows (PowerShell):

```powershell
move vibetty-windows-x64.exe $env:USERPROFILE\.cargo\bin\vibetty.exe
```

<details>
<summary>What is PATH?</summary>
Expand Down Expand Up @@ -99,52 +92,134 @@ echo $PATH | grep -q "$HOME/.cargo/bin" && echo "Yes" || echo "No"
```
</details>

## Quick Start

```bash
# For pre-built binary
mv vibetty ~/.cargo/bin/
Vibetty defaults to **Whisper** mode (cloud transcription). The fastest path:

# Or for self-compiled binary
mv target/release/vibetty ~/.cargo/bin/
**1. Get a Whisper API key.** Groq is recommended. You can also use OpenAI, GLM, ByteFuture, or any Whisper-compatible endpoint.

**2. Configure ASR** with the interactive wizard (writes `~/.vibetty/config.toml`):

```bash
vibetty setup
```

Manual environment-variable configuration is covered in [Configuration](#configuration).

**3. Start the server with your agent.** Anything after `--` is launched in the terminal, so Vibetty works with any coding agent CLI:

| Agent | Launch command |
|---|---|
| Claude Code | `vibetty -- claude` |
| OpenAI Codex | `vibetty -- codex` |
| Gemini CLI | `vibetty -- gemini` |
| OpenCode | `vibetty -- opencode` |
| aider | `vibetty -- aider` |
| Plain shell | `vibetty -- bash` |

The agent CLI must already be installed and on your `PATH`.

**4. Pair your VibeKeys Max.** Open `http://localhost:3000/setup` and connect to the keyboard over Bluetooth. Set the **VibeKeys server WebSocket URL** to your Vibetty server (e.g. `ws://<your-host>:3000/ws`) and choose a **Microphone Mode** (PushToTalk or Toggle).

**5. Watch the terminal.** Open `http://localhost:3000` to see the live session. Speak into the keyboard and your words run as commands.

For all options:

```bash
# For pre-built binary
mv vibetty ~/.cargo/bin/
vibetty --help
```

# Or for self-compiled binary
mv target/release/vibetty ~/.cargo/bin/
## Configuration

Vibetty supports two speech-recognition backends. Configure either interactively or via environment variables.

### Interactive setup (recommended)

```bash
vibetty setup
```

##### Option 2: WebVosk (Browser-side)
A TUI walks you through:
1. Select a platform: **Whisper** or **WebVosk**
2. If Whisper, choose a provider preset: **OpenAI**, **ByteFuture**, **Groq**, **GLM**, or **Custom**
3. Fill in the API key and other settings
4. Settings are saved to `~/.vibetty/config.toml`

Speech recognition runs entirely in the browser using Vosk models. No API key required.
### Whisper (default)

**Option A: Download pre-built binary**
Server-side transcription via a Whisper-compatible API. Create a `.env` file (or set these in your shell profile, e.g. `~/.bashrc` / `~/.zshrc`):

```bash
# Set ASR platform and run
VIBECODE_ASR_PLATFORM=web_vosk ./vibetty -- claude
VIBECODE_ASR_API_KEY=your_api_key_here
VIBECODE_ASR_URL=https://api.groq.com/openai/v1/audio/transcriptions
VIBECODE_ASR_MODEL=whisper-large-v3
VIBECODE_ASR_LANG=en
VIBECODE_ASR_PROMPT=
```

**Option B: Build from source**
Then start the service:

```bash
# Set ASR platform and run
VIBECODE_ASR_PLATFORM=web_vosk ./vibetty -- -- claude
vibetty -- claude
```

Then visit the WebVosk interface at: http://localhost:3000/vosk
### WebVosk — offline, no API key

**Note:** First-time use requires downloading Vosk model files (~40MB each). The models are cached in your browser.
Speech recognition runs entirely in the browser using Vosk models. No API key required, and no audio is sent to a cloud service.

For more options, use `--help`:
```bash
./vibetty --help
VIBECODE_ASR_PLATFORM=web_vosk vibetty -- claude
```

Then open the WebVosk interface at `http://localhost:3000/vosk`.

**Note:** First-time use downloads Vosk model files (~40MB each). The models are cached in your browser.

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `VIBECODE_ASR_PLATFORM` | ASR platform to use: `whisper` or `web_vosk` | `whisper` |
| `VIBECODE_ASR_URL` | Whisper API endpoint URL | `https://api.openai.com/v1/audio/transcriptions` |
| `VIBECODE_ASR_API_KEY` | Whisper API key (Groq recommended) | _(empty)_ |
| `VIBECODE_ASR_MODEL` | Whisper model name | `whisper-1` |
| `VIBECODE_ASR_LANG` | ASR language (e.g. `en`, `zh`) | _(empty, auto-detected by API)_ |
| `VIBECODE_ASR_PROMPT` | Prompt passed to the Whisper API to guide transcription | _(empty)_ |
| `VIBECODE_ASR_DEBUG_WAV` | Set to any value to save recorded audio as `debug_<session_id>.wav` for debugging | _(unset)_ |
| `VIBECODE_EXIT_COMMAND` | Custom voice exit command. When ASR result matches this value (case-insensitive), it is replaced with `/exit` | _(unset)_ |

> **Note:** Legacy environment variables (e.g. `ASR_URL`, `ASR_API_KEY`, `VIBETTY_EXIT_COMMAND`, etc.) have been renamed with the `VIBECODE_` prefix. Using old names will trigger a warning but still work. Please migrate to the new names.

## Platform Support

Vibetty runs on **Linux**, **macOS**, and **Windows**.

| Platform | PTY backend | Requirements |
|---|---|---|
| Linux | Unix PTY | — |
| macOS | Unix PTY | — |
| Windows | ConPTY (via [`portable-pty-psmux`](https://crates.io/crates/portable-pty-psmux)) | Windows 10 (1809+) or Windows 11 |

### Running on Windows

The quick-start commands above use Unix-style paths; on Windows, use the `.exe` and backslash paths from **PowerShell** or **Command Prompt**:

```powershell
# Pre-built binary
.\vibetty-windows-x64.exe -- claude

# Or build from source
cargo build --release
.\target\release\vibetty.exe -- claude
```

Visit: http://localhost:3000 after starting the service.
Set environment variables with `$env:` in PowerShell:

```powershell
$env:VIBECODE_ASR_API_KEY = "your_api_key_here"
$env:VIBECODE_ASR_URL = "https://api.groq.com/openai/v1/audio/transcriptions"
.\vibetty.exe -- claude
```

## API Reference

Expand Down Expand Up @@ -175,22 +250,3 @@ curl -X POST http://localhost:3000/api/change-dir \
```

**Note:** This endpoint only accepts requests from localhost for security reasons.

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `VIBECODE_ASR_PLATFORM` | ASR platform to use: `whisper` or `web_vosk` | `whisper` |
| `VIBECODE_ASR_URL` | Whisper API endpoint URL | `https://api.openai.com/v1/audio/transcriptions` |
| `VIBECODE_ASR_API_KEY` | Whisper API key (Groq recommended) | _(empty)_ |
| `VIBECODE_ASR_MODEL` | Whisper model name | `whisper-1` |
| `VIBECODE_ASR_LANG` | ASR language (e.g. `en`, `zh`) | _(empty, auto-detected by API)_ |
| `VIBECODE_ASR_PROMPT` | Prompt passed to the Whisper API to guide transcription | _(empty)_ |
| `VIBECODE_ASR_DEBUG_WAV` | Set to any value to save recorded audio as `debug_<session_id>.wav` for debugging | _(unset)_ |
| `VIBECODE_EXIT_COMMAND` | Custom voice exit command. When ASR result matches this value (case-insensitive), it is replaced with `/exit` | _(unset)_ |

> **Note:** Legacy environment variables (e.g. `ASR_URL`, `ASR_API_KEY`, `VIBETTY_EXIT_COMMAND`, etc.) have been renamed with the `VIBECODE_` prefix. Using old names will trigger a warning but still work. Please migrate to the new names.

## Platform Support

Supports **Linux**, **macOS**, and **Windows** (via ConPTY).
Loading