An interactive terminal controlled by voice, with local or cloud speech and AI providers.
- Control Bash, Zsh, or Fish by voice.
- Use Ollama, OpenAI, Anthropic, or any command-line AI.
- Pick local, cloud, or custom HTTP speech providers.
- Ignore steady background noise before transcription.
flowchart LR
User((User))
Voice[Voice input]
Recognition[Speech recognition]
Route{Transcript route}
Processor[Response processor]
Reply[Speech + command]
Speech[Speech output]
Session[VSH session]
Shell[Interactive shell]
Client[Monitoring client]
HTTP[Read-only HTTP interface]
User -->|keyboard input| Session
User -->|voice| Voice --> Recognition --> Route
Route -->|direct command| Session
Route -->|process| Processor --> Reply
Reply -->|speech| Speech --> User
Reply -->|command| Session
Client -->|request| HTTP
Session -->|status + output| HTTP
HTTP -->|response| Client
Session -->|shell input| Shell
Shell -->|shell output| Session
Session -->|terminal output| User
Keyboard and voice commands operate on the same live shell session. The optional HTTP interface only observes it.
The Nix package includes its native audio dependencies. For uv installs, install PortAudio; Linux also requires ALSA development libraries.
# uv
uv tool install git+https://github.com/creator54/vsh.git
# Nix
nix profile install github:creator54/vsh- Local checkout:
uv tool install -e .
vsh: start the shell.--voice: start listening immediately.--verbose: show logs.--echo: return recognized speech without an AI.--serve [--instance-id NAME]: expose read-only shell status and output over a private Unix socket; prints the socket path. IDs default to random and accept 1–32 ASCII letters, digits, underscores or hyphens.
vsh setup: configure the shell, speech and AI providers, microphone, and keybind.vsh bind: change the VSH toggle keybind.vsh stt [--file <audio.wav>]: transcribe the microphone or a WAV file.vsh tts "<text>" [--save <out.wav>] [--stream]: speak or save text.
- Format:
{"speech":"Opening it.","command":"cd ~/project"}- Use
nullwhen there is no command. - Invalid JSON is shown as text and never run.
- Use
- Speech comes first.
- TTS available: play it.
- TTS off or failed: print it.
- Command comes next.
auto_submit = true: run it.auto_submit = false: leave it editable.
- Shell and voice:
VSH_SHELL,VSH_VOICE. - AI provider:
VSH_LLM,VSH_LLM_KEY. - Output:
VSH_OUTPUT_MODE(speak_and_command,command_only, orspeak_only). - Visual:
VSH_OVERLAY(auto,kitty, ornone). - Voice command:
VSH_VOICE_HANDLER='command {}'. - Local bridge: HTTP over
$XDG_RUNTIME_DIR/vsh/<instance-id>.sock, or${TMPDIR:-/tmp}/vsh-<uid>/<instance-id>.sockwhenXDG_RUNTIME_DIRis unset. The directory is 0700 and the socket is 0600; access is restricted to the same OS user (and privileged processes), without bearer tokens or a TCP listener. Unsafe existing directories are rejected, not repaired.- Read-only endpoints:
GET /health,GET /tools(empty),GET /io/output./healthretains the existing shell state field; it is not a reliable command-readiness signal.POST /execute_toolremains disabled (410). - Example:
curl --unix-socket "$XDG_RUNTIME_DIR/vsh/demo.sock" http://localhost/healthafter startingvsh --serve --instance-id demo. - Replaces
--portandVSH_SERVER_TOKEN. Consumers must connect through the socket; do not forward it over TCP. Live paths and unrelated files are never overwritten; refused connections on owned stale sockets allow reclamation.
- Read-only endpoints:
- Press the configured keybind (default
Ctrl+\),Ctrl+G, orCtrl+]to toggle voice capture.- Off: remove the voice indicator and restore the normal cursor.
- On: follow the system microphone's mute state (Linux/PipeWire).