pi-voice 0.1.0 → 0.2.0

package/README.md

@@ -1,78 +1,93 @@
 # pi-voice
 
-## Setup
+Headless voice interface for the [Pi Coding Agent](https://github.com/badlogic/pi-mono). Hold a key, speak, and pi executes your instructions with voice feedback.
+
+https://github.com/user-attachments/assets/06a0c56f-76bf-48cb-9de3-f9ca48a7245d
+
+## Installation
 
 ```bash
-bun install
-bun run build
-bun link          # `pi-voice` コマンドをグローバルに登録
+npm i -g pi-voice
+# or
+bun i -g pi-voice
 ```
 
-## CLI
+## Usage
 
-pi-voice は **daemon 型**のアプリケーションです。Docker と同じように、`start` でバックグラウンドに常駐し、CLI で操作します。起動時にウィンドウは表示されません。
-
-`status` / `stop` / `show` は Electron を起動せず、Unix socket 経由で daemon と通信して即応します。
+pi-voice is a daemon-style application that runs in the background once started. You can push-to-talk with the agent.
 
 ```bash
-# daemon をバックグラウンドで起動（ウィンドウは表示されない）
-pi-voice start
+pi-voice start    # start the daemon in the background
+pi-voice status   # show state, PID, and uptime
+pi-voice stop     # stop the daemon
+```
 
-# daemon の状態を確認（state・PID・uptime を表示）
-pi-voice status
+The push-to-talk trigger defaults to `Cmd+Shift+I` (macOS) / `Win+Shift+I` (Windows). Hold the key to record, release to send.
 
-# ウィンドウを表示
-pi-voice show
+## Setting
 
-# daemon を停止（Fn キーも無効化）
-pi-voice stop
-```
+### pi agent configuration
 
-- `start` は引数なしのデフォルトコマンドです。既に起動中ならエラーで終了します。
-- `start` は事前に `bun run build` が必要です（`out/main/index.js` がなければエラー）。
-- ウィンドウを閉じても daemon はバックグラウンドで動作し続けます。完全に停止するには `stop` か Cmd+Q を使ってください。
-- 実行状態は `~/.pi-voice/runtime-state.json`、制御 socket は `~/.pi-voice/daemon.sock` に配置されます。
+pi-voice launches a Pi agent session with the directory where `pi-voice start` was executed. This means **all standard pi configuration works as-is**:
 
-### 開発モード
+- `AGENTS.md` — walked up from `cwd` to the filesystem root
+- `.pi/settings.json` — project-level settings
+- `.pi/skills/`, `.pi/extensions/`, `.pi/prompts/` — project-level resources
+- `~/.pi/agent/` — global settings, skills, extensions, prompts, and models
+- and more
 
-```bash
-bun run dev:electron
-```
+Refer to the [Pi documentation](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) for details on these settings.
 
-HMR 付きの Vite dev server で renderer を配信しつつ Electron を起動します（開発時はウィンドウを閉じると終了します）。
+### pi-voice configuration
 
-CLI 単体で実行する場合:
+You can configure pi-voice in `.pi/pi-voice.json`:
 
-```bash
-bun run dev:cli
+```json
+{
+  "key": "ctrl+t",
+  "provider": "local"
+}
 ```
 
-## Build
+| Key | Description |
+| --- | --- |
+| `key` | Push-to-talk shortcut. Combine modifiers (`ctrl`, `shift`, `alt`/`opt`, `meta`/`cmd`) and a main key with `+`. Examples: `"ctrl+t"`, `"alt+space"`, `"ctrl+shift+r"`. Default: `"meta+shift+i"`. |
+| `provider` | Speech provider for STT & TTS. `"local"`, `"gemini"` (Vertex AI), or `"openai"`. Default: `"local"`. |
 
-```bash
-bun run build
-```
+### Environment variables
+
+| Provider | Required variables |
+| --- | --- |
+| `local` | None (model is auto-downloaded on first launch). Optional: `WHISPER_MODEL_PATH` (custom model path), `WHISPER_MODEL` (model name, default `medium-q5_0`), `SAY_VOICE` (macOS `say` voice name, e.g. `"Kyoko"`). |
+| `gemini` | `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION` (optional, default `us-central1`) |
+| `openai` | `OPENAI_API_KEY` |
+
+#### Logging
 
-`out/` にプロダクションビルドを出力します。
+The daemon writes structured JSON logs to both the console and a log file. The default log file path is `$XDG_CONFIG_HOME/pi-voice/daemon.log` (falls back to `~/.config/pi-voice/daemon.log`).
 
-## Preview
+To override the log file path:
 
 ```bash
-bun run preview
+export PI_VOICE_LOG_PATH=/path/to/custom.log
 ```
 
-ビルド済みの成果物で Electron を起動して動作確認します。
+#### Whisper model (local provider)
 
-## Distribution
+The `local` provider uses [Whisper](https://github.com/openai/whisper) for STT and the macOS `say` command for TTS. On first launch, a ggml-format Whisper model (`medium-q5_0`, ~514 MB) is automatically downloaded to `~/.pi-agent/whisper/` and cached for subsequent runs.
+
+To use a different model, set `WHISPER_MODEL`:
 
 ```bash
-bun run dist
+export WHISPER_MODEL=base     # smaller & faster
 ```
 
-`bun run build` + electron-builder で macOS 向けの dmg/zip を `release/` に生成します。
-
-パッケージングせずディレクトリ出力のみ（テスト用）:
+Or point to your own model file directly:
 
 ```bash
-bun run dist:dir
+export WHISPER_MODEL_PATH=/path/to/ggml-custom.bin
 ```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, build commands, and release workflow.