yazses 1.2.0

Local, offline voice dictation for Linux, macOS, and Windows — hold a key, speak, release

YazSes

Hold a key → speak → release. On-device voice dictation that types into any app, plus voice commands and macros — entirely offline. No cloud. No API key. No subscription.

---

Two versions of YazSes

This repo holds one product with two implementations — not two separate apps, but two generations of the same idea. The one you install and run is Part 1 (Python), on this main branch.

	Part 1 — Python · main	Rust HCI exploration · archive/rust-hci-v1
What it is	The shipping app — voice dictation, commands, macros	An early-stage rewrite exploring deeper human–computer interaction: an on-device agent (LLM tool-use, personal memory, editor awareness)
Status	✅ Active — current product (v0.9.0, installed & maintained)	⏸️ Paused / archived — not shipped, not installable
Hold-to-talk dictation	✅	✅
Offline STT	✅ faster-whisper	✅ Whisper + Moonshine v2 (~9 ms)
Voice commands → key sequences	✅ regex grammar (+ optional SLM router)	✅ via LLM tool-calls
Voice macros · Mid-Thought Undo · Punch-In · Prosody Ink · Ghost Ahead	✅	❌
Dysfluency-Friendly Mode · learning corpus + yazses tune	✅	❌
Friendly CLI (-h, examples, yazses update)	✅	❌
On-device LLM agent (20 tools: git commit, media, notes, screenshots…)	❌ (optional offline text cleanup only)	✅
Personal memory (encrypted on-device vector store)	❌	✅
Editor context (Neovim / VS Code)	✅ LSP context, opt-in	✅ 5-tier window detection + bridges
Screen-reader accessibility (AT-SPI / NVDA)	❌	✅
Packaged & distributed (PyPI, snap, APT, …)	✅	❌

Bottom line: if you want YazSes, use Part 1 (this branch). The Rust branch is kept only for reference — nothing on main builds, installs, or depends on it. The Rust effort aimed at a more ambitious agentic HCI layer but was left in early stages; revisiting it is a deliberate future decision, not part of day-to-day work here.

---

Quick Start

Step 1 — Install

Platform	Command
Linux (Debian/Ubuntu)	bash <(curl -fsSL https://raw.githubusercontent.com/novafabric/yazses/main/install-apt.sh)
Linux (any distro)	pipx install yazses
macOS	brew tap novafabric/yazses && brew install --cask yazses
Windows	winget install NovaFabric.YazSes

Step 2 — Set up

yazses doctor               # check everything is ready
yazses model pull qwen3-7b  # download the AI model (~5 GB, one-time)
yazses enroll               # calibrate your microphone (30 seconds)
yazses start                # start the daemon

Step 3 — Use it

OS	Hold this key	Say anything
Linux	Space	"open terminal", "commit add new feature", "type hello world"
macOS	Right Option	"set volume to 50", "take a screenshot called mockup"
Windows	Right Ctrl	"remember my meeting is at 3pm", "what did I tell you yesterday?"

Release the key — YazSes acts within one second.

First time on macOS? Right-click the app → Open (Gatekeeper), then grant Accessibility + Microphone when prompted.

First time on Windows? If SmartScreen warns you, click More info → Run anyway.

First time on Linux? Run sudo usermod -aG input "$USER" and re-login before starting.

---

What you can say

YazSes understands natural language and maps it to 20 built-in actions:

Say something like…	What happens
"type hello world"	Types text at the cursor
"commit added login feature"	Runs git add -A && git commit -m "added login feature"
"open main.py"	Opens the file
"go to function parse_config"	Jumps to the symbol via LSP
"set volume to 30"	Sets system volume
"take a screenshot called diagram"	Saves diagram.png
"remember my password expires on June 1"	Stores in encrypted local memory
"what did I remember about passwords?"	Queries local memory
"set a timer for 25 minutes"	Starts a countdown
"open VS Code"	Launches the application
"press Control S"	Sends the key chord

---

How it works

Hold hotkey → record audio → speech-to-text → local LLM → pick tool → execute

Everything runs on your CPU. The LLM (Qwen3-7B by default) reads the transcript and decides which of the 20 tools to call. Result appears in the focused window within ~1 second on a modern laptop.

Models used:

• STT: Moonshine v2 (9 ms, streaming) for short commands · Whisper-large-v3-turbo for long dictation
• LLM: llama.cpp with GBNF tool-call grammar (Qwen3-7B default) · Ollama backend optional

---

Requirements

OS	Linux (primary) · macOS 13+ · Windows 10+
RAM	8 GB minimum · 16 GB recommended
Disk	6–10 GB for the default model
CPU	4+ cores · no GPU required
Mic	Any USB or built-in microphone

---

Key features

• Fully offline — no audio, no text, no data leaves the machine by default
• Agent, not just dictation — understands intent, not just words
• Dual STT stack — fast streaming for commands, accurate long-form for dictation
• Personal memory — encrypted local vector store, voice-queryable
• Editor integration — Neovim and VS Code LSP context improves accuracy on code identifiers
• Accessibility — AT-SPI (Linux) and NVDA (Windows) screen-reader support; Talon coexistence
• EMG support — works with muscle sensors for motor-disability use cases

---

CLI commands

Command	Description
yazses start	Start the YazSes daemon in the background
yazses stop	Stop the running daemon
yazses status	Show daemon status — queries the daemon over IPC when reachable
yazses doctor	Check system prerequisites (mic, AT-SPI, injection backend, permissions)
yazses enroll	Calibrate your microphone — records 20 utterances to tune vad_threshold and min_silence_ms
yazses mic-level	Measure mic speech level and recommend (or set with --set) the VAD threshold
yazses overlay	Launch the sonar voice-activity overlay in the foreground (requires overlay extra)
yazses inject TEXT	Type arbitrary text into the focused window — useful to test injection without speaking
yazses test	End-to-end self-test: focuses a window and types YazSes OK to confirm injection works
yazses logs	Show the daemon diagnostic log (metadata only — no dictated text is stored)
yazses mark-wrong	Flag the last dictation as a misrecognition (feeds the learning corpus)
yazses tune	Analyse the learning corpus and propose accuracy improvements; --apply to write changes
yazses corpus	Manage the local learning corpus (status, forget, destroy)
yazses model	Download and manage SLM intent-routing models
yazses remote HOST	Forward voice typing to a remote host over SSH

---

Configuration

Config file location:

OS	Path
Linux	~/.config/yazses/config.toml
macOS	~/Library/Application Support/yazses/config.toml
Windows	%APPDATA%\yazses\config.toml

Essential settings:

[hotkey]
key = "auto"               # Space (Linux) / right_option (macOS) / right_ctrl (Windows)
hold_threshold_ms = 500    # how long to hold before recording starts

[llm]
model_path = ""            # empty = use the model from `yazses model pull`

[stt]
backend = "auto"           # "moonshine" (fast) | "whisper" (accurate) | "auto"

[audio]
device = ""                # empty = system default microphone

[memory]
passphrase = ""            # set a passphrase to encrypt the memory store

See the CLI reference for all options.

Microphone not working?

If YazSes does nothing and the log shows Silent audio -- discarding:

yazses mic-level --set   # measure your voice and set the right threshold
yazses stop && yazses start

---

All install options

Linux

# APT repo — Debian / Ubuntu (recommended)
bash <(curl -fsSL https://raw.githubusercontent.com/novafabric/yazses/main/install-apt.sh)

# PPA — Ubuntu
sudo add-apt-repository ppa:novafabric/yazses && sudo apt install yazses

# Snap
sudo snap install yazses --classic

# AUR — Arch / Manjaro
yay -S yazses

# pipx (Python v0.4.x)
sudo apt install libportaudio2 xdotool xclip pipx
pipx install yazses

macOS

# Homebrew Cask (recommended)
brew tap novafabric/yazses && brew install --cask yazses

# Direct download
# https://github.com/novafabric/yazses/releases/latest

Windows

# winget (recommended)
winget install NovaFabric.YazSes

# Direct download
# https://github.com/novafabric/yazses/releases/latest

---

Documentation

Install on Linux	Detailed Linux guide — permissions, injection backends, service setup
Install on macOS	Gatekeeper, Accessibility, Microphone permissions
Install on Windows	SmartScreen, antivirus exceptions, privacy settings
CLI reference	All commands and flags
Plugin SDK	Adding custom tools and voice commands
Privacy statement	What stays on-device, what is never collected
Migration v0.4 → v1.0	Upgrading from the Python version

---

Development

YazSes (Part 1) is a Python project managed with uv:

git clone https://github.com/novafabric/yazses
cd yazses
uv sync
uv run python -m pytest tests/ -v
bash scripts/install-local.sh        # install locally + run as a user service

Rust HCI exploration (archived)

The early-stage Rust rewrite lives on the archive/rust-hci-v1 branch, not on main. It is not built or installed by anything here — see Two versions of YazSes above for what it does and doesn't have. To look at it:

git checkout archive/rust-hci-v1
cargo build && cargo test --workspace   # optional backends: whisper, moonshine, llama-cpp, ollama, silero

---

License

Apache 2.0 — see LICENSE.

If YazSes is useful to you, a ⭐ on GitHub and a mention in your project, blog, or talk is the best way to support continued development.