Installing SigmaShake Voice

SigmaShake Voice is a headless, offline voice-to-text daemon. 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.

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​