Developers
Your terminal is already powerful. Now it can talk back.
The shellvoice command turns any line of shell into a spoken message. Put it at the end of a build, in a git hook, or in the loop of an AI agent, and stop watching the window.
shellvoice speak "Build completed successfully"shellvoice notify "Claude needs your attention"echo "Deploy finished" | shellvoice speakshellvoice statusShellVoice is running version 0.1.0 dictation idle speech idle model installed shortcut Alt+SpaceReference
Five commands. All of them real.
This is the complete surface of the CLI in the current build.
| Usage | What it does | Example |
|---|---|---|
| shellvoice speak <text> | Speak text aloud through ShellVoice with your chosen voice. | shellvoice speak "Build completed successfully" |
| shellvoice notify <text> | Speak the text and show a macOS notification. Both can be toggled in Settings → General. | shellvoice notify "Claude needs your attention" |
| shellvoice status | Show the running app's version, dictation and speech state, installed model and shortcut. | shellvoice status |
| shellvoice stop | Stop the current speech immediately. | shellvoice stop |
| shellvoice config | Print the socket path and the settings file location. | shellvoice config |
Text can also be piped: echo "Deploy finished" | shellvoice speak. Run shellvoice --help for the same list in your terminal.
Installation
Install the CLI.
The command-line tool talks to the running desktop app, so it needs ShellVoice installed first. In 0.1.0 the CLI binary is built with cargo; the app links it onto your PATH.
- 1
Build the binary
cargo build --release -p shellvoice-cli produces target/release/shellvoice. The bundled app does not embed it yet.
- 2
Install from Settings → Developer
The Developer section shows whether the CLI is installed and links it into ~/.local/bin. Make sure that folder is on your PATH.
- 3
Keep the app running
The CLI connects to the app over a local socket. ShellVoice can stay in the menu bar.
Integrations
Anywhere a command can run, ShellVoice can speak.
There is no plugin system to learn. These are ordinary shell lines you add to tools you already use.
# say the result of any long commandsay_done() { "$@" && shellvoice notify "Done: $1" || shellvoice notify "Failed: $1"; }say_done cargo build --release"scripts": { "test": "vitest run", "test:say": "pnpm test && shellvoice notify \"All tests passed\""}#!/bin/shshellvoice speak "Merge finished. Dependencies may have changed."# wrap any CLI agent; speak when it exits or waitsclaude -p "$TASK"; shellvoice notify "Claude finished the task and needs your attention"You write these lines; ShellVoice provides the voice. Automatic hooks that detect Claude Code, Codex and Gemini CLI events are planned so the wrapper line becomes unnecessary.
How it works
A local socket, nothing else.
- Talks to the running app over a Unix domain socket in the app's data directory, created with 0600 permissions — local and user-only.
- Text is capped at 10,000 characters and stripped of control characters before it is spoken.
- Nothing is ever executed as a shell command; the app only speaks or notifies.
- If the app is not running the CLI says so and exits non-zero, so scripts can handle it.
In the current build
Available today- speak, notify, status, stop, config; stdin piping
- Spoken and system notifications, each switchable in Settings
- Custom dictionary that biases local recognition toward your terms
- Local Whisper models; optional OpenAI-compatible cloud endpoint
On the roadmap
Planned- Built-in event detection for Claude Code, Codex and Gemini CLI
- Streaming transcription and voice commands
- Per-app profiles; more speech-to-text and text-to-speech providers
- Windows support; Keychain-backed secrets
Follow the changelog for what has actually shipped.
Give your Mac a voice.
Dictate anywhere. Hear your tools. Keep everything on your machine.
- macOS
- Available for macOS
- Windows
- Windows planned
Version 0.1.0 for macOS 12.0+ · Signed builds are being prepared