From ad5bc7268449c807e6ef0341dbd0a13339af349e Mon Sep 17 00:00:00 2001
From: alabulei1 <vivian.xiage@gmail.com>
Date: Wed, 24 Jun 2026 12:30:58 +0800
Subject: [PATCH 1/4] docs: add Windows install and run instructions

Windows support landed in #8 (portable-pty-psmux / ConPTY) but the docs
only mentioned it in a one-line note. Add real Windows usage:

- README.md: expand Platform Support into a per-platform table with
  requirements, plus a "Running on Windows" section (vibetty-windows-x64.exe,
  PowerShell $env: vars, %PATH% placement)
- docs/README.zh.md: add the equivalent platform-support section in Chinese

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md         | 38 +++++++++++++++++++++++++++++++++++++-
 docs/README.zh.md | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 54b3e3d..5e5d21d 100644
--- a/README.md
+++ b/README.md
@@ -193,4 +193,40 @@ curl -X POST http://localhost:3000/api/change-dir \
 
 ## Platform Support
 
-Supports **Linux**, **macOS**, and **Windows** (via ConPTY).
+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
+
+Pre-built releases include a Windows binary named `vibetty-windows-x64.exe`. 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
+```
+
+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
+```
+
+To run `vibetty` from any directory, move the binary into a folder on your `PATH`
+(for example `%USERPROFILE%\.cargo\bin`):
+
+```powershell
+move vibetty.exe $env:USERPROFILE\.cargo\bin\
+```
diff --git a/docs/README.zh.md b/docs/README.zh.md
index 4ca8160..c3d5e61 100644
--- a/docs/README.zh.md
+++ b/docs/README.zh.md
@@ -107,3 +107,40 @@ curl -X POST http://localhost:3000/api/change-dir \
 ```
 
 **注意：** 出于安全考虑，此接口仅接受来自 localhost 的请求。
+
+## 平台支持
+
+Vibetty 支持 **Linux**、**macOS** 和 **Windows**。
+
+| 平台 | PTY 后端 | 系统要求 |
+|---|---|---|
+| Linux | Unix PTY | — |
+| macOS | Unix PTY | — |
+| Windows | ConPTY（基于 [`portable-pty-psmux`](https://crates.io/crates/portable-pty-psmux)） | Windows 10（1809+）或 Windows 11 |
+
+### 在 Windows 上运行
+
+预编译版本包含名为 `vibetty-windows-x64.exe` 的 Windows 二进制文件。上面的快速开始命令使用的是 Unix 风格路径；在 Windows 上请在 **PowerShell** 或**命令提示符**中使用 `.exe` 和反斜杠路径：
+
+```powershell
+# 预编译二进制
+.\vibetty-windows-x64.exe -- claude
+
+# 或从源码编译
+cargo build --release
+.\target\release\vibetty.exe -- claude
+```
+
+在 PowerShell 中可用 `$env:` 设置环境变量：
+
+```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
+```
+
+如需在任意目录下运行 `vibetty`，请将二进制文件移动到 `PATH` 中的目录（例如 `%USERPROFILE%\.cargo\bin`）：
+
+```powershell
+move vibetty.exe $env:USERPROFILE\.cargo\bin\
+```

From ccc9e6b971b4d7ddf9db5aec8134743ff1e5b23f Mon Sep 17 00:00:00 2001
From: alabulei1 <vivian.xiage@gmail.com>
Date: Wed, 24 Jun 2026 14:56:01 +0800
Subject: [PATCH 2/4] docs: restructure README around Whisper-first,
 keyboard-direct flow

The README buried installation inside the Whisper config section and
presented Whisper/WebVosk as equal options. Restructure to match how the
product actually works:

- Add a "How it works" section: VibeKeys Max mic streams audio over
  WebSocket to the server, which transcribes via a Whisper API and injects
  text into the terminal + agent. (Audio source is the keyboard, not the
  browser; the browser only displays the terminal.)
- Split Installation out of Configuration; one PATH block (was duplicated),
  per-OS release asset names, Windows binary.
- Make Whisper the default path; demote WebVosk to "offline, no API key".
- Quick Start now covers pairing the VibeKeys Max via /setup over Bluetooth.
- Fix the WebVosk `-- --` typo.
- Mirror the same structure in docs/README.zh.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md         | 165 ++++++++++++++++++++++++----------------------
 docs/README.zh.md | 155 ++++++++++++++++++++++++++++++-------------
 2 files changed, 199 insertions(+), 121 deletions(-)

diff --git a/README.md b/README.md
index 5e5d21d..9e0c2e8 100644
--- a/README.md
+++ b/README.md
@@ -1,73 +1,64 @@
 # 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 Claude Code (or any terminal program), served over the web.
 
-## Features
-
-- **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)
-
-## Quick Start
+## How it works
 
-### ASR Configuration
+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.
 
-Vibetty supports two speech recognition modes:
+```
+VibeKeys Max mic ──WebSocket──▶ Vibetty server ──WAV──▶ Whisper API ──text──▶ terminal + agent
+ (push-to-talk / toggle)
+```
 
-#### Interactive Setup (Recommended)
+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).
 
-Run the setup wizard to configure ASR interactively:
+## Features
 
-```bash
-vibetty setup
-```
+- **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
+- **Claude AI Integration** - AI-assisted terminal interaction
+- **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)
 
-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`
+## Installation
 
-#### Manual Configuration
+### Option A: Download a pre-built binary
 
-You can also configure ASR manually via environment variables.
+Download the latest release for your platform from the [releases page](https://github.com/second-state/vibetty/releases):
 
-##### Option 1: Whisper API (Server-side)
+| Platform | Asset |
+|---|---|
+| Linux | `vibetty-linux-x64` |
+| macOS (Apple Silicon) | `vibetty-macos-arm64` |
+| Windows | `vibetty-windows-x64.exe` |
 
-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`):
+### Option B: Build from source
 
 ```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
 ```
 
-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>
@@ -99,52 +90,81 @@ echo $PATH | grep -q "$HOME/.cargo/bin" && echo "Yes" || echo "No"
 ```
 </details>
 
+## Quick Start
+
+Vibetty defaults to **Whisper** mode (cloud transcription). The fastest path:
+
+**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
-# For pre-built binary
-mv vibetty ~/.cargo/bin/
+vibetty setup
+```
 
-# Or for self-compiled binary
-mv target/release/vibetty ~/.cargo/bin/
+Manual environment-variable configuration is covered in [Configuration](#configuration).
+
+**3. Start the server with your agent:**
+
+```bash
+vibetty -- claude
 ```
 
+**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
 ```
 
-Visit: http://localhost:3000 after starting the service.
+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.
 
 ## API Reference
 
@@ -203,9 +223,7 @@ Vibetty runs on **Linux**, **macOS**, and **Windows**.
 
 ### Running on Windows
 
-Pre-built releases include a Windows binary named `vibetty-windows-x64.exe`. The
-quick-start commands above use Unix-style paths; on Windows, use the `.exe` and
-backslash paths from **PowerShell** or **Command Prompt**:
+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
@@ -223,10 +241,3 @@ $env:VIBECODE_ASR_API_KEY = "your_api_key_here"
 $env:VIBECODE_ASR_URL     = "https://api.groq.com/openai/v1/audio/transcriptions"
 .\vibetty.exe -- claude
 ```
-
-To run `vibetty` from any directory, move the binary into a folder on your `PATH`
-(for example `%USERPROFILE%\.cargo\bin`):
-
-```powershell
-move vibetty.exe $env:USERPROFILE\.cargo\bin\
-```
diff --git a/docs/README.zh.md b/docs/README.zh.md
index c3d5e61..d128526 100644
--- a/docs/README.zh.md
+++ b/docs/README.zh.md
@@ -1,43 +1,114 @@
 # Vibetty
 
-WebSocket 终端服务器，支持语音输入和 Claude AI 智能交互。
+面向 AI 编程 agent 的语音终端。对着 **VibeKeys Max** 键盘说话，Vibetty 会把语音转写后直接送进 Claude Code（或任意终端程序），并通过网页提供访问。
+
+## 工作原理
+
+你对着 VibeKeys Max 键盘的内置麦克风说话（按住说话 / 切换模式）。键盘把音频通过 WebSocket 流式传到 Vibetty 服务端。在默认的 **Whisper** 模式下，服务端把音频打包成 WAV 发送给 Whisper 兼容 API（Groq、OpenAI、GLM…），再把转写出的文本注入终端会话以及其中运行的 AI agent。浏览器页面用于显示实时终端。
+
+```
+VibeKeys Max 麦克风 ──WebSocket──▶ Vibetty 服务端 ──WAV──▶ Whisper API ──文本──▶ 终端 + agent
+ （按住说话 / 切换）
+```
+
+不想用云端 API？**WebVosk** 模式可以完全在浏览器本地做语音识别，无需 API Key，详见 [WebVosk](#webvosk离线无需-api-key)。
 
 ## 功能特性
 
 - **WebSocket 终端** - 基于 Axum 框架的实时终端 Web 接口
-- **语音输入** - 支持语音转文字，可通过语音执行命令
-- **Claude AI 集成** - 使用 `echokit_terminal` 实现 AI 辅助终端交互
-- **多种 ASR 支持**
-  - OpenAI Whisper API
-  - 阿里云 Paraformer 实时语音识别(todo)
+- **语音输入** - 通过 VibeKeys Max 麦克风说话，语音转写为文本
+- **Claude AI 集成** - AI 辅助终端交互
+- **多种 ASR 后端**
+  - Whisper API —— OpenAI、Groq、GLM、ByteFuture 或任意自定义端点（默认）
+  - WebVosk —— 离线、浏览器内、无需 API Key
+  - 阿里云 Paraformer 实时语音识别（todo）
+
+## 安装
+
+### 方式 A：下载预编译二进制
+
+从 [releases 页面](https://github.com/second-state/vibetty/releases) 下载对应平台的最新版本：
+
+| 平台 | 文件 |
+|---|---|
+| Linux | `vibetty-linux-x64` |
+| macOS（Apple Silicon） | `vibetty-macos-arm64` |
+| Windows | `vibetty-windows-x64.exe` |
+
+### 方式 B：从源码编译
+
+```bash
+cargo build --release
+# 二进制位于 ./target/release/vibetty
+```
+
+### 加入 PATH（可选）
+
+如需在任意目录下运行 `vibetty`，把二进制文件放进 `PATH` 中的目录，推荐 `~/.cargo/bin`：
+
+```bash
+# 预编译二进制
+mv vibetty ~/.cargo/bin/
+
+# 或自行编译的二进制
+mv target/release/vibetty ~/.cargo/bin/
+```
+
+Windows（PowerShell）：
+
+```powershell
+move vibetty-windows-x64.exe $env:USERPROFILE\.cargo\bin\vibetty.exe
+```
 
 ## 快速开始
 
-### ASR 配置
+Vibetty 默认使用 **Whisper** 模式（云端转写）。最快路径：
+
+**1. 获取 Whisper API Key。** 推荐 Groq，也可使用 OpenAI、GLM、ByteFuture 或任意 Whisper 兼容端点。
 
-Vibetty 支持两种语音识别模式：
+**2. 配置 ASR**，运行交互式向导（会写入 `~/.vibetty/config.toml`）：
 
-#### 交互式配置（推荐）
+```bash
+vibetty setup
+```
 
-运行配置向导来交互式配置 ASR：
+手动通过环境变量配置见 [配置](#配置)。
+
+**3. 启动服务并带上你的 agent：**
+
+```bash
+vibetty -- claude
+```
+
+**4. 配对 VibeKeys Max。** 打开 `http://localhost:3000/setup`，通过蓝牙连接键盘。把 **VibeKeys 服务器 WebSocket 地址** 设为你的 Vibetty 服务端（例如 `ws://<你的主机>:3000/ws`），并选择**麦克风模式**（PushToTalk 或 Toggle）。
+
+**5. 查看终端。** 打开 `http://localhost:3000` 看到实时会话。对着键盘说话，你的话会作为命令执行。
+
+查看全部参数：
+
+```bash
+vibetty --help
+```
+
+## 配置
+
+Vibetty 支持两种语音识别后端，可交互式配置，也可通过环境变量配置。
+
+### 交互式配置（推荐）
 
 ```bash
 vibetty setup
 ```
 
-启动后会进入 TUI 界面，可以：
+进入 TUI 界面，可以：
 1. 选择平台：**Whisper** 或 **WebVosk**
-2. 如果选择 Whisper，可以选择提供商预设：**OpenAI**、**ByteFuture**、**Groq**、**GLM** 或 **Custom**
+2. 如果选择 Whisper，可选择提供商预设：**OpenAI**、**ByteFuture**、**Groq**、**GLM** 或 **Custom**
 3. 填写 API Key 等配置项
 4. 配置保存到 `~/.vibetty/config.toml`
 
-#### 手动配置
-
-也可以通过环境变量手动配置 ASR。
-
-##### 选项 1：Whisper API（服务器端）
+### Whisper（默认）
 
-创建 `.env` 文件并配置 Whisper API（推荐使用 Groq）：
+服务端通过 Whisper 兼容 API 转写。创建 `.env` 文件（或写入 shell 配置文件，如 `~/.bashrc` / `~/.zshrc`）：
 
 ```bash
 VIBECODE_ASR_API_KEY=your_api_key_here
@@ -50,34 +121,21 @@ VIBECODE_ASR_PROMPT=
 然后启动服务：
 
 ```bash
-# 使用 cargo 直接运行
-cargo run -- -- claude
-
-# 或者先编译再运行
-cargo build --release
-./target/release/vibetty -- claude
+vibetty -- claude
 ```
 
-##### 选项 2：WebVosk（浏览器端）
+### WebVosk（离线，无需 API Key）
 
-语音识别完全在浏览器中使用 Vosk 模型运行，无需 API 密钥。
+语音识别完全在浏览器中使用 Vosk 模型运行，无需 API 密钥，音频也不会发送到云端。
 
 ```bash
-# 设置 ASR 平台为 WebVosk
-VIBECODE_ASR_PLATFORM=web_vosk cargo run -- -- claude
+VIBECODE_ASR_PLATFORM=web_vosk vibetty -- claude
 ```
 
-然后访问 WebVosk 界面：http://localhost:3000/vosk
+然后访问 WebVosk 界面：`http://localhost:3000/vosk`
 
 **注意：** 首次使用需要下载 Vosk 模型文件（每个约 40MB）。模型会缓存在浏览器中。
 
-更多参数可以使用 `--help` 命令查看：
-```bash
-cargo run -- --help
-```
-
-服务启动后访问: http://localhost:3000
-
 ## API 参考
 
 ### 更改目录
@@ -108,6 +166,21 @@ curl -X POST http://localhost:3000/api/change-dir \
 
 **注意：** 出于安全考虑，此接口仅接受来自 localhost 的请求。
 
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|---|---|---|
+| `VIBECODE_ASR_PLATFORM` | 使用的 ASR 平台：`whisper` 或 `web_vosk` | `whisper` |
+| `VIBECODE_ASR_URL` | Whisper API 端点 URL | `https://api.openai.com/v1/audio/transcriptions` |
+| `VIBECODE_ASR_API_KEY` | Whisper API Key（推荐 Groq） | _(空)_ |
+| `VIBECODE_ASR_MODEL` | Whisper 模型名 | `whisper-1` |
+| `VIBECODE_ASR_LANG` | ASR 语言（如 `en`、`zh`） | _(空，由 API 自动检测)_ |
+| `VIBECODE_ASR_PROMPT` | 传给 Whisper API 用于引导转写的提示词 | _(空)_ |
+| `VIBECODE_ASR_DEBUG_WAV` | 设为任意值即可把录音保存为 `debug_<session_id>.wav` 用于调试 | _(未设置)_ |
+| `VIBECODE_EXIT_COMMAND` | 自定义语音退出命令。当 ASR 结果（不区分大小写）匹配该值时，替换为 `/exit` | _(未设置)_ |
+
+> **注意：** 旧版环境变量（如 `ASR_URL`、`ASR_API_KEY`、`VIBETTY_EXIT_COMMAND` 等）已统一加上 `VIBECODE_` 前缀。使用旧名称会有警告但仍可工作，请尽快迁移到新名称。
+
 ## 平台支持
 
 Vibetty 支持 **Linux**、**macOS** 和 **Windows**。
@@ -120,7 +193,7 @@ Vibetty 支持 **Linux**、**macOS** 和 **Windows**。
 
 ### 在 Windows 上运行
 
-预编译版本包含名为 `vibetty-windows-x64.exe` 的 Windows 二进制文件。上面的快速开始命令使用的是 Unix 风格路径；在 Windows 上请在 **PowerShell** 或**命令提示符**中使用 `.exe` 和反斜杠路径：
+上面的快速开始命令使用 Unix 风格路径；在 Windows 上请在 **PowerShell** 或**命令提示符**中使用 `.exe` 和反斜杠路径：
 
 ```powershell
 # 预编译二进制
@@ -131,16 +204,10 @@ cargo build --release
 .\target\release\vibetty.exe -- claude
 ```
 
-在 PowerShell 中可用 `$env:` 设置环境变量：
+在 PowerShell 中用 `$env:` 设置环境变量：
 
 ```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
 ```
-
-如需在任意目录下运行 `vibetty`，请将二进制文件移动到 `PATH` 中的目录（例如 `%USERPROFILE%\.cargo\bin`）：
-
-```powershell
-move vibetty.exe $env:USERPROFILE\.cargo\bin\
-```

From 3f45b55dcf2050fe6d145028b780f0734dcec5a4 Mon Sep 17 00:00:00 2001
From: alabulei1 <vivian.xiage@gmail.com>
Date: Wed, 24 Jun 2026 15:15:41 +0800
Subject: [PATCH 3/4] docs: move API Reference to the end of README and zh doc

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md         | 60 +++++++++++++++++++++++------------------------
 docs/README.zh.md | 60 +++++++++++++++++++++++------------------------
 2 files changed, 60 insertions(+), 60 deletions(-)

diff --git a/README.md b/README.md
index 9e0c2e8..0697aed 100644
--- a/README.md
+++ b/README.md
@@ -166,36 +166,6 @@ 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.
 
-## API Reference
-
-### Change Directory
-
-Change the current working directory via HTTP API.
-
-**Endpoint:** `POST /api/change-dir`
-
-**Request:**
-```bash
-curl -X POST http://localhost:3000/api/change-dir \
-  -H "Content-Type: application/json" \
-  -d '{"path": "/path/to/directory"}'
-```
-
-**Example:**
-```bash
-# Change to absolute path
-curl -X POST http://localhost:3000/api/change-dir \
-  -H "Content-Type: application/json" \
-  -d '{"path": "/home/user/documents"}'
-
-# Change to relative path
-curl -X POST http://localhost:3000/api/change-dir \
-  -H "Content-Type: application/json" \
-  -d '{"path": "../parent-folder"}'
-```
-
-**Note:** This endpoint only accepts requests from localhost for security reasons.
-
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -241,3 +211,33 @@ $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
+
+### Change Directory
+
+Change the current working directory via HTTP API.
+
+**Endpoint:** `POST /api/change-dir`
+
+**Request:**
+```bash
+curl -X POST http://localhost:3000/api/change-dir \
+  -H "Content-Type: application/json" \
+  -d '{"path": "/path/to/directory"}'
+```
+
+**Example:**
+```bash
+# Change to absolute path
+curl -X POST http://localhost:3000/api/change-dir \
+  -H "Content-Type: application/json" \
+  -d '{"path": "/home/user/documents"}'
+
+# Change to relative path
+curl -X POST http://localhost:3000/api/change-dir \
+  -H "Content-Type: application/json" \
+  -d '{"path": "../parent-folder"}'
+```
+
+**Note:** This endpoint only accepts requests from localhost for security reasons.
diff --git a/docs/README.zh.md b/docs/README.zh.md
index d128526..9014017 100644
--- a/docs/README.zh.md
+++ b/docs/README.zh.md
@@ -136,36 +136,6 @@ VIBECODE_ASR_PLATFORM=web_vosk vibetty -- claude
 
 **注意：** 首次使用需要下载 Vosk 模型文件（每个约 40MB）。模型会缓存在浏览器中。
 
-## API 参考
-
-### 更改目录
-
-通过 HTTP API 更改当前工作目录。
-
-**接口地址：** `POST /api/change-dir`
-
-**请求格式：**
-```bash
-curl -X POST http://localhost:3000/api/change-dir \
-  -H "Content-Type: application/json" \
-  -d '{"path": "/path/to/directory"}'
-```
-
-**使用示例：**
-```bash
-# 切换到绝对路径
-curl -X POST http://localhost:3000/api/change-dir \
-  -H "Content-Type: application/json" \
-  -d '{"path": "/home/user/documents"}'
-
-# 切换到相对路径
-curl -X POST http://localhost:3000/api/change-dir \
-  -H "Content-Type: application/json" \
-  -d '{"path": "../parent-folder"}'
-```
-
-**注意：** 出于安全考虑，此接口仅接受来自 localhost 的请求。
-
 ## 环境变量
 
 | 变量 | 说明 | 默认值 |
@@ -211,3 +181,33 @@ $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 参考
+
+### 更改目录
+
+通过 HTTP API 更改当前工作目录。
+
+**接口地址：** `POST /api/change-dir`
+
+**请求格式：**
+```bash
+curl -X POST http://localhost:3000/api/change-dir \
+  -H "Content-Type: application/json" \
+  -d '{"path": "/path/to/directory"}'
+```
+
+**使用示例：**
+```bash
+# 切换到绝对路径
+curl -X POST http://localhost:3000/api/change-dir \
+  -H "Content-Type: application/json" \
+  -d '{"path": "/home/user/documents"}'
+
+# 切换到相对路径
+curl -X POST http://localhost:3000/api/change-dir \
+  -H "Content-Type: application/json" \
+  -d '{"path": "../parent-folder"}'
+```
+
+**注意：** 出于安全考虑，此接口仅接受来自 localhost 的请求。

From 2e4cf95ee9e153c3f13de927e118917c44079db1 Mon Sep 17 00:00:00 2001
From: alabulei1 <vivian.xiage@gmail.com>
Date: Wed, 24 Jun 2026 15:49:20 +0800
Subject: [PATCH 4/4] docs: clarify Vibetty is agent-agnostic with per-agent
 launch commands

Vibetty runs whatever follows `--` in a PTY; there is no Claude-specific
code. Reflect that:

- Tagline/features now name Claude Code, Codex, Gemini CLI, OpenCode,
  aider as examples (Vibetty has no hard dependency on any one agent).
- Quick Start step 3 lists launch commands per agent
  (vibetty -- claude / codex / gemini / opencode / aider / bash).
- Mirror both in docs/README.zh.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md         | 23 ++++++++++++++++-------
 docs/README.zh.md | 23 ++++++++++++++++-------
 2 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 0697aed..2e5c6c2 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Vibetty
 
-Voice-driven terminal for AI coding agents. Speak into a **VibeKeys Max** keyboard and Vibetty transcribes your speech straight into Claude Code (or any terminal program), served over the web.
+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.
 
 ## How it works
 
@@ -17,7 +17,7 @@ Prefer not to use a cloud API? **WebVosk** mode runs speech recognition locally
 
 - **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
-- **Claude AI Integration** - AI-assisted terminal interaction
+- **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
@@ -37,9 +37,11 @@ Download the latest release for your platform from the [releases page](https://g
 
 ### Option B: Build from source
 
+Requires [Rust](https://rustup.rs/).
+
 ```bash
 cargo build --release
-# binary at ./target/release/vibetty
+# binary at ./target/release/vibetty  (vibetty.exe on Windows)
 ```
 
 ### Add to your PATH (optional)
@@ -104,11 +106,18 @@ vibetty setup
 
 Manual environment-variable configuration is covered in [Configuration](#configuration).
 
-**3. Start the server with your agent:**
+**3. Start the server with your agent.** Anything after `--` is launched in the terminal, so Vibetty works with any coding agent CLI:
 
-```bash
-vibetty -- claude
-```
+| 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).
 
diff --git a/docs/README.zh.md b/docs/README.zh.md
index 9014017..4859165 100644
--- a/docs/README.zh.md
+++ b/docs/README.zh.md
@@ -1,6 +1,6 @@
 # Vibetty
 
-面向 AI 编程 agent 的语音终端。对着 **VibeKeys Max** 键盘说话，Vibetty 会把语音转写后直接送进 Claude Code（或任意终端程序），并通过网页提供访问。
+面向 AI 编程 agent 的语音终端。对着 **VibeKeys Max** 键盘说话，Vibetty 会把语音转写后直接送进你选择的编程 agent —— Claude Code、Codex、Gemini CLI —— 或任意终端程序，并通过网页提供访问。
 
 ## 工作原理
 
@@ -17,7 +17,7 @@ VibeKeys Max 麦克风 ──WebSocket──▶ Vibetty 服务端 ──WAV─
 
 - **WebSocket 终端** - 基于 Axum 框架的实时终端 Web 接口
 - **语音输入** - 通过 VibeKeys Max 麦克风说话，语音转写为文本
-- **Claude AI 集成** - AI 辅助终端交互
+- **Agent 无关** - 可包裹任意基于终端的编程 agent（Claude Code、Codex、Gemini CLI、OpenCode、aider…）或任意 shell 命令 —— Vibetty 不绑定任何单一 agent
 - **多种 ASR 后端**
   - Whisper API —— OpenAI、Groq、GLM、ByteFuture 或任意自定义端点（默认）
   - WebVosk —— 离线、浏览器内、无需 API Key
@@ -37,9 +37,11 @@ VibeKeys Max 麦克风 ──WebSocket──▶ Vibetty 服务端 ──WAV─
 
 ### 方式 B：从源码编译
 
+需要安装 [Rust](https://rustup.rs/)。
+
 ```bash
 cargo build --release
-# 二进制位于 ./target/release/vibetty
+# 二进制位于 ./target/release/vibetty（Windows 上为 vibetty.exe）
 ```
 
 ### 加入 PATH（可选）
@@ -74,11 +76,18 @@ vibetty setup
 
 手动通过环境变量配置见 [配置](#配置)。
 
-**3. 启动服务并带上你的 agent：**
+**3. 启动服务并带上你的 agent。** `--` 后面的内容都会在终端里启动，所以 Vibetty 适配任意 coding agent CLI：
 
-```bash
-vibetty -- claude
-```
+| Agent | 启动命令 |
+|---|---|
+| Claude Code | `vibetty -- claude` |
+| OpenAI Codex | `vibetty -- codex` |
+| Gemini CLI | `vibetty -- gemini` |
+| OpenCode | `vibetty -- opencode` |
+| aider | `vibetty -- aider` |
+| 纯 shell | `vibetty -- bash` |
+
+对应的 agent CLI 需要已经安装并在你的 `PATH` 中。
 
 **4. 配对 VibeKeys Max。** 打开 `http://localhost:3000/setup`，通过蓝牙连接键盘。把 **VibeKeys 服务器 WebSocket 地址** 设为你的 Vibetty 服务端（例如 `ws://<你的主机>:3000/ws`），并选择**麦克风模式**（PushToTalk 或 Toggle）。