Installing SigmaShake Voice

SigmaShake Voice is a headless voice-to-text daemon that transcribes locally by default. It ships as a single Go binary that is both the daemon and its control CLI. Transcription runs on-device via whisper.cpp (cgo binding) with no account or internet connection required for the default local Whisper backend. If you enable the optional NVIDIA NIM backend with your own key, the daemon sends your audio to NVIDIA.

The daemon runs as a systemd --user unit and exposes an HTTP+WebSocket API on 127.0.0.1:5650. An optional browser settings UI is served from the same process on port 1430.

Platform note. The evdev hotkey and /dev/uinput paste injection are Linux-specific. On macOS and Windows the daemon starts and the HTTP API works, but the in-process hotkey is not active — use an OS-level shortcut that calls sigmashake-voice --toggle instead (see Hotkeys).

Prerequisites

Go 1.26+ with cgo enabled (gcc/g++ required)
cmake (for the one-time whisper.cpp static library build)
Bun (used for the monorepo build scripts and the optional MCP server)
Linux: user in the input group for hotkey and paste injection (see Linux permissions)

For CUDA-accelerated transcription: the CUDA toolkit must be installed before building.

Build

Run these commands from the monorepo root:

# 1. Download the Whisper GGML model (~547 MB) into resources/ — only needed once
bash sigmashake-voice/scripts/fetch-model.sh

# 2. Build whisper.cpp static libraries + the Go binary
bun run voice:build

bun run voice:build runs two steps:

build:whisper — cmake build of third_party/whisper.cpp into static libs under go/internal/whisper/lib/. Uses a power-safe bounded job count (override with WHISPER_BUILD_JOBS).
build:core — CGO_ENABLED=1 go build -o go/dist/sigmashake-voice ./cmd/sigmashake-voice

The resulting binary is at go/dist/sigmashake-voice.

CUDA build:

bun run voice:build:cuda

At runtime, the daemon uses the GPU backend by default when a CUDA build is present. Set SIGMASHAKE_VOICE_GPU=0 to force CPU. In a CPU-only build SIGMASHAKE_VOICE_GPU is a no-op.

Run

One-off (foreground)

bun run voice:dev       # build + run the daemon in the foreground
# or directly:
go/dist/sigmashake-voice

The daemon writes its live port to <data-dir>/voice.port and logs to <data-dir>/voice.YYYY-MM-DD.log.

systemd --user unit (production)

The repository ships a unit template at systemd/sigmashake-voice.service.template. Install it by substituting __SSG_VOICE_DIR__ with the absolute path to the sigmashake-voice/ directory, then enable it:

# Render the template (replace /your/path/to/sigmashake-voice with the real path)
sed 's|__SSG_VOICE_DIR__|/your/path/to/sigmashake-voice|g' \
    sigmashake-voice/systemd/sigmashake-voice.service.template \
    > ~/.config/systemd/user/sigmashake-voice.service

systemctl --user daemon-reload
systemctl --user enable --now sigmashake-voice

Check status:

systemctl --user status sigmashake-voice
journalctl --user -u sigmashake-voice -f

Control CLI

sigmashake-voice is both the daemon and a control surface. When the daemon is already running, subcommands send HTTP requests to it:

Subcommand	Action
`sigmashake-voice` / `sigmashake-voice daemon`	Run the headless daemon
`sigmashake-voice toggle` / `-t`	Toggle recording on/off
`sigmashake-voice rearm`	Rebuild the audio capture device
`sigmashake-voice chat-toggle`	Toggle voice-to-chat broadcast arm
`sigmashake-voice health`	Print daemon health (`/health`)
`sigmashake-voice state`	Print current recording state
`sigmashake-voice settings`	Print current settings
`sigmashake-voice stats`	Print dictation stats
`sigmashake-voice devices`	List available audio input devices
`sigmashake-voice chat-broadcast`	Print chat-broadcast arm status
`sigmashake-voice --paste-test`	Run clipboard/paste-injection diagnostic

The CLI scans ports 5650–5660 for the running daemon. Override with the VOICE_PORT environment variable.

Linux permissions

Hotkey

The in-process hotkey reads /dev/input/event* directly (evdev). Your user must be in the input group:

sudo usermod -aG input $USER

Log out and back in — group membership takes effect on the next login session.

Paste injection

Paste injection uses /dev/uinput (the same mechanism as ydotool). The input group membership added above is sufficient on most distributions. If your system uses a separate uinput group:

sudo usermod -aG uinput $USER

Then log out and back in again.

Hotkeys

Linux Wayland (in-process evdev)

Once the input group is set, configure a single bare key in the browser settings UI or via the HTTP API. Modifier combos are not supported by the evdev watcher:

Works	Does not work
`F9`	`Ctrl+F9`
`Pause`	`Ctrl+Shift+Space`
`ScrollLock`	`Super+F9`

Supported keys: F1–F20, Pause, ScrollLock, PrintScreen, Insert, Home, End, PageUp, PageDown, Delete.

OS-level shortcut (any platform, or for modifier combos)

Bind a keyboard shortcut in your desktop environment to call sigmashake-voice --toggle. The CLI scans 5650–5660 to find the daemon.

GNOME: Settings → Keyboard → Custom Shortcuts
KDE Plasma: System Settings → Shortcuts → Custom Shortcuts
COSMIC: Settings → Keyboard Shortcuts → Custom → Add

Use the full absolute path to the binary, for example:

/home/yourname/sigmashake-mono/sigmashake-voice/go/dist/sigmashake-voice --toggle

Browser settings UI

The daemon optionally serves a browser settings UI at http://127.0.0.1:1430. Open this URL in any browser to configure your hotkey, microphone, and paste mode. The UI is served from the web/ directory by the daemon process — no separate server is needed.

Data directory

Settings and logs are stored in the data directory, resolved in this order:

$SIGMASHAKE_VOICE_DIR
<binary directory>/sigmashake-voice-data/
<user config dir>/sigmashake-voice

The daemon migrates a legacy ~/.sigmashake/voice.json into the data directory on first run.

Environment variables

Variable	Purpose
`VOICE_PORT`	Override daemon port (default: scans 5650–5660)
`SIGMASHAKE_VOICE_DIR`	Override data directory
`SIGMASHAKE_VOICE_MODEL`	Path to a custom GGML model file
`SIGMASHAKE_VOICE_GPU`	Set to `0` to force CPU inference
`SIGMASHAKE_VOICE_BROADCAST_URL`	URL for voice-to-chat broadcast
`SIGMASHAKE_VOICE_BROADCAST_AUTO`	Set to `1` to broadcast when tmux focus gate allows (defaults OFF)
`SIGMASHAKE_VOICE_BROADCAST_BYPASS_FOCUS`	Set to `1` to skip the tmux focus gate

Agent MCP server

tools/voice-mcp.ts is a stdio MCP server that exposes the daemon's HTTP API as typed MCP tools. It is a thin HTTP client and works against the running Go daemon with no additional configuration.

claude mcp add sigmashake-voice -- bun /absolute/path/to/sigmashake-voice/tools/voice-mcp.ts

Run directly:

bun tools/voice-mcp.ts

See Usage for recording, transcription, and paste workflows.

Prerequisites​

Build​

Run​

One-off (foreground)​

systemd --user unit (production)​

Control CLI​

Linux permissions​

Hotkey​

Paste injection​

Hotkeys​

Linux Wayland (in-process evdev)​

OS-level shortcut (any platform, or for modifier combos)​

Browser settings UI​

Data directory​

Environment variables​

Agent MCP server​