Skip to content

Mirach Documentation

Local-first voice assistant daemon. Press a hotkey, talk, get an answer spoken back — with conversation memory, tool use, and ~3 s round-trip latency.

Quick start

git clone https://github.com/JosLuna1098/mirach ~/mirach && python3 ~/mirach/install.py

What is Mirach?

Mirach is a voice assistant that runs as a background daemon on your Linux desktop:

  • STT: faster-whisper — Whisper medium on GPU, ~0.5 s
  • LLM: OpenCode CLI — your choice of model with full tool ecosystem
  • TTS: Piper — local neural TTS, ~0.3 s
  • Control: Single hotkey (default Alt+Z) for record, process, and interrupt

How it works

  1. Press your hotkey → high beep → start talking
  2. Press again → low beep → Mirach transcribes, queries the LLM, speaks the answer
  3. Press during processing → interrupts immediately, starts new recording

Key features

  • No always-on listening — mic only opens on hotkey
  • Session persistence — conversations survive daemon restarts
  • Progressive feedback — fillers and notifications during long LLM calls
  • User scripts — custom voice-triggered commands without LLM overhead
  • Bilingual — English and Spanish UI, triggers, and filler phrases
  • Extensible — OpenCode skills for web search, app control, system monitoring, and more

Documentation structure

This documentation follows the Diátaxis framework:

Section Purpose
Tutorial Learn by doing — install and have your first conversation
How-to Guides Solve specific problems — add scripts, change voices, troubleshoot
Reference Technical details — all configuration options, architecture
Explanation Understand the why — design decisions and tradeoffs

Requirements

  • Linux desktop (Wayland or X11 with notify-send)
  • Python 3.11+
  • NVIDIA GPU with CUDA 12 (CPU mode works with higher latency)
  • A microphone

Next steps

Inspiration

This project was inspired by Nate Gentile's video Mi PC Linux ahora trabaja por mí (CachyOS + IA).