![\"claude-voice](\"./assets/demo.svg\")
\n\n\n\n` | switch language for STT + TTS (e.g. `/lang hi`, `/lang auto`) |\n| `/stream` | toggle speaking-as-Claude-writes vs speaking the whole reply at once |\n| `/quit` | exit |\n\nWhile listening, a live **mic-level meter** in the status bar fills green as it hears you, so you always know the mic is working. Claude's answer streams to the screen as it's written and is **spoken as it streams** — text is chunked one **sentence** at a time and each sentence is synthesized *ahead* of playback, so audio starts moments after the first sentence and tracks the text as it appears. Sentences are the unit (rather than clauses) so the TTS engine voices internal punctuation — commas, dashes, colons — as natural pauses: splitting on every comma makes engines like Kokoro pad each fragment with a beat of trailing silence, i.e. an audible stop at each mark. For the lowest possible first-word latency at the cost of choppier prosody, **`--fast-speech`** chunks at clause boundaries instead. Generation, synthesis, and playback all run in parallel and never block each other.\n\nFor **gapless** streaming, install `ffmpeg` (`brew install ffmpeg`): the reply is fed sentence-by-sentence into a single persistent audio stream (`ffplay`), which waits during pauses rather than reopening the device — so it sounds like one continuous answer. Without a streaming player it falls back to playing a few back-to-back clips via `afplay` (a small seam between clips), and `--no-stream` (or `/stream`) speaks the whole reply at once with no seams at all. sox `play` is intentionally not used for streaming — it cuts off on the first pause.\n\nWhile Claude generates, the status bar shows a live **word count and words/sec**, and each reply is tagged with its time and length (e.g. `Claude · 2.4s · 45w`).\n\n> The rich UI needs a real terminal. When output is piped or `CLAUDE_VOICE_PLAIN=1` is set, it falls back to a plain streaming UI.\n\n### Commands\n\n| Command | What it does |\n| --- | --- |\n| `claude-voice` / `claude-voice chat` | Start a live voice conversation. |\n| `claude-voice serve` | Host a remote voice client on your Wi-Fi — talk to Claude from your phone. |\n| `claude-voice say \"\"` | Speak a phrase aloud with the configured voice (no mic needed). |\n| `claude-voice config` | View or edit configuration. |\n| `claude-voice local` | Set up / check the fully-local, free stack (whisper.cpp + Kokoro). |\n| `claude-voice doctor` | Diagnose your setup (CLI, keys, mic, speaker, network). |\n| `claude-voice update` | Check for and install the latest version. |\n| `claude-voice version` | Print the installed version. |\n\n## ⬆️ Updating\n\nAlready installed it? Upgrade to the latest published version:\n\n```bash\n# global install:\nnpm install -g @aayushdebugging/claude-voice@latest\n\n# or, if it's a project dependency:\nnpm update @aayushdebugging/claude-voice\n```\n\nFrom **v0.1.2** onward you can also self-update in place:\n\n```bash\nclaude-voice update # checks npm and installs the newest version\nclaude-voice update --check # just check, don't install\nclaude-voice version # what you're on now\n```\n\n> Note: `npm update` takes a bare package name (no `@latest`); use `npm install …@latest` to force the newest, or `npm update …` to move within your saved range.\n\n## 🔒 Fully local & free (no API keys)\n\nRun entirely offline with open-source models — no cloud, no keys, $0:\n\n- **STT:** [whisper.cpp](https://github.com/ggml-org/whisper.cpp) (Metal-accelerated on Apple Silicon)\n- **TTS:** [Kokoro](https://github.com/hexgrad/kokoro) (`kokoro-onnx`, CPU, no PyTorch)\n\nIt's a few one-time steps. **`claude-voice local` downloads the models and reports\nstatus; you install the native runtimes once and start the two local servers**\n(npm can't install compiled binaries, and the servers are long-running, so those\nstay in your hands).\n\n**1. Install the runtimes** (one-time — native/Python, not from npm):\n\n| Platform | Command |\n| --- | --- |\n| macOS | `brew install sox ffmpeg whisper-cpp uv` |\n| Debian/Ubuntu | `sudo apt-get install sox ffmpeg` · then [build whisper.cpp](https://github.com/ggml-org/whisper.cpp#quick-start) and [install `uv`](https://docs.astral.sh/uv/getting-started/installation/) |\n\n**2. Download the models + check what's needed:**\n\n```bash\nclaude-voice local\n```\nThis **auto-downloads the whisper model** (~150 MB, with a progress bar), writes the\nKokoro server script to `~/.claude-voice/kokoro-server.py`, and prints a ✔/✖ status\nreport with the exact command for anything still missing. (`--no-download` prints the\nmodel's `curl` command instead of fetching it.)\n\n**3. Start the two servers** — each in its own terminal, since they keep running:\n\n```bash\n# speech-to-text (whisper.cpp)\nwhisper-server -m ~/.claude-voice/models/ggml-base.en.bin --host 127.0.0.1 --port 8081\n\n# text-to-speech (Kokoro — downloads its ~340 MB model on first run)\nuv run --with kokoro-onnx --with numpy python ~/.claude-voice/kokoro-server.py --port 8880\n```\n\n**4. Talk, pointed at the local stack:**\n\n```bash\nclaude-voice --local\n# …or make it the permanent default:\nclaude-voice config --set stt=whispercpp --set tts=kokoro --set voice=af_heart\n```\n\n> Re-run `claude-voice local` any time to see live status (which servers are up, which\n> models exist). If you see `whisper.cpp request failed: fetch failed`, a server just\n> isn't running yet — start it with step 3.\n\nAny OpenAI-compatible STT/TTS server works too (point `providers.whispercpp.baseUrl` /\n`providers.kokoro.baseUrl` at it).\n\n## 📱 Talk from your phone (remote)\n\nRun a token-protected voice session on your machine and drive it from your phone on the same Wi-Fi — hands-free with headphones:\n\n```bash\nclaude-voice serve\n```\n\nIt prints a link and a **QR code**. Scan it (or open the link) on your phone:\n\n1. Accept the one-time certificate warning (it's a self-signed cert — needed so the phone's browser will allow microphone access on the LAN).\n2. Allow microphone access.\n3. **Hold the button, speak, release.** Your words are transcribed on your machine, sent to Claude, and the reply streams back as text and **plays aloud on the phone**. Tap **Stop** to cut off a reply, or type instead.\n\n> **Safe by default.** A remote session runs with **all of Claude's tools disabled** — it can talk, but it can't run shell commands, edit files, or read your disk. The link carries a secret token, but anyone on your network who has it can talk to Claude on your machine, so only share it with yourself.\n\n```bash\nclaude-voice serve --host 127.0.0.1 # keep it on this machine only\nclaude-voice serve --port 8080 # change the port\nclaude-voice serve --max-clients 2 # cap simultaneous devices\nclaude-voice serve --allow-tools # DANGER: let remote prompts run tools\n```\n\nPlease read [SECURITY.md](./SECURITY.md) before using `--allow-tools` or exposing the server on an untrusted network.\n\n## 🔑 Configuration\n\nConfiguration lives at `~/.claude-voice/config.json`. **API keys are never\nstored there** — they are read from environment variables:\n\n| Provider | Env var |\n| --- | --- |\n| Groq (STT, default) | `GROQ_API_KEY` |\n| OpenAI (STT) | `OPENAI_API_KEY` |\n| ElevenLabs (TTS, default) | `ELEVENLABS_API_KEY` |\n| Sarvam (TTS) | `SARVAM_API_KEY` |\n\n```jsonc\n{\n \"stt\": \"groq\", // \"groq\" | \"openai\"\n \"tts\": \"elevenlabs\", // \"elevenlabs\" | \"sarvam\"\n \"voice\": \"aria\", // TTS voice name\n \"model\": \"opus\", // Claude model alias\n \"pushToTalk\": false, // continuous vs push-to-talk\n \"autoSpeak\": true, // speak responses aloud\n \"streamSpeech\": true, // speak as Claude writes (vs the whole reply at once)\n \"voicePrompt\": \"…\", // steers Claude to answer in a voice-friendly way (\"\" disables)\n \"language\": \"auto\", // STT + TTS language (ISO-639-1) or \"auto\"\n \"speechRate\": 1.0, // speech rate multiplier, 0.5–3.0 (1 = natural)\n \"silenceTimeoutMs\": 1500, // silence that ends an utterance\n \"micSensitivity\": 150, // lower = picks up quieter mics; higher = ignores noise\n \"sampleRate\": 16000\n}\n```\n\nManage it from the CLI:\n\n```bash\nclaude-voice config # print current config + path\nclaude-voice config --edit # open in $EDITOR\nclaude-voice config --set voice=river --set model=sonnet\nclaude-voice config --get providers.groq.model\nclaude-voice config --reset # restore defaults\n```\n\n## 🧠 How it works\n\n```\n🎤 Microphone → 📝 Speech-to-Text → 🤖 Claude CLI (stream-json)\n ↑ ↓\n barge-in 🔎 Sentence parser\n ↑ ↓ ↓\n 🔊 Speakers ← 🗣️ TTS queue ←──────────┘ 🖥️ Terminal (live tokens)\n```\n\nClaude's output is streamed token-by-token. A streaming **sentence parser**\naccumulates tokens until a sentence completes (`.`, `?`, `!`, or a paragraph\nbreak), then hands each finished sentence to an **interruptible speech queue**\nso audio begins while Claude is still generating. Every stage communicates over\na typed **event bus**, so the UI, plugins, and providers stay decoupled.\n\nRead the full [Architecture guide](./docs/ARCHITECTURE.md).\n\n## 🧩 Programmatic use\n\n`claude-voice` is also a library. The CLI is a thin layer over these primitives:\n\n```ts\nimport { createSession, loadConfig } from '@aayushdebugging/claude-voice';\n\nconst config = await loadConfig({ model: 'opus', voice: 'river' });\nconst { conversation, bus } = createSession({ config });\n\nbus.on('SpeechRecognized', ({ text }) => console.log('You said:', text));\nbus.on('ClaudeToken', ({ text }) => process.stdout.write(text));\n\nawait conversation.start(); // Ctrl-C to stop\n```\n\nSee the [API documentation](./docs/API.md) for the full surface, including how\nto write custom STT/TTS providers and plugins.\n\n## 🩺 Troubleshooting\n\nRun `claude-voice doctor` first — it pinpoints most issues. Common ones:\n\n- **\"Claude CLI not found\"** — install it from and ensure `claude` is on your `PATH`.\n- **\"recording backend not found\"** / **\"Microphone capture needs sox\"** — install `sox` (`brew install sox`; see the table above).\n- **\"No microphone audio detected\"** — either `sox` isn't installed, or your terminal lacks mic permission. Install `sox`, then grant access under **System Settings → Privacy & Security → Microphone** (to the *terminal app you launched from* — e.g. Terminal, iTerm, or VS Code) and restart it.\n- **\"whisper.cpp request failed: fetch failed\"** (or the same for `kokoro`) — the local STT/TTS **server isn't running**. Start it (see [Fully local & free](#-fully-local--free-no-api-keys), step 3) or run `claude-voice local` to see which servers are up. `fetch failed` = nothing is listening on the configured port.\n- **\"speaker module unavailable\"** — the optional native audio module failed to build; install your platform's build tools and reinstall. `--no-speak` works meanwhile.\n- **401 from a provider** — double-check the corresponding `*_API_KEY`.\n\n## 🔐 Security\n\n`claude-voice` drives the Claude CLI — a capable agent — from your voice. Local\nsessions have full tool access (like your terminal); **remote (`serve`) sessions\ndisable all tools by default** so a spoken or injected prompt can't run commands\nor touch your files. Before exposing a server or using `--allow-tools`, read\n[**SECURITY.md**](./SECURITY.md) for the threat model and safe-use guidance. To\nreport a vulnerability, see the reporting section there (please don't file a\npublic issue).\n\n## 🤝 Contributing\n\nContributions are very welcome! See the [Contributing guide](./docs/CONTRIBUTING.md)\nfor the dev setup, coding standards, and how to add a provider or plugin.\n\n## 📄 License\n\n[MIT](./LICENSE) © claude-voice contributors\n","readmeFilename":"README.md"}