Getting Started (Dev Setup)
Relevant source files
The following files were used as context for generating this wiki page:
mausVoice is a high-performance, cross-platform desktop application designed for voice-to-text dictation with AI cleanup. The project is architected as a Turborepo monorepo utilizing Tauri v2, which bridges a Rust backend for native capabilities with a TypeScript/React frontend for application logic.
This guide outlines the environment configuration and steps necessary to build, run, and contribute to the repository. The project follows a strict "Rust is the API, TypeScript is the Brain" philosophy, where all business logic is managed via Zustand state in the frontend, while Rust handles low-level tasks such as audio capture, global hotkeys, and SQLite management.
Sources: llms.txt:1-20, apps/desktop/README.md:40-45, CLAUDE.md:14-25
Prerequisites
Before beginning the setup, ensure your development machine meets the following hardware and software requirements.
System Requirements
| Requirement | Minimum Version / Note |
|---|---|
| Node.js | 18+ (v24 recommended for dev) |
| Package Manager | pnpm 10+ |
| Rust Toolchain | 1.77+ (Tauri v2 compatible) |
| Cmake | Required for whisper-rs |
| Platform Tools | Xcode CLT (macOS), Visual Studio Build Tools (Windows) |
Sources: README.md:89-92, llms.txt:23-28, apps/desktop/README.md:7-12, scripts/setup-macos.sh:65-75
Development Environment Diagram
The following diagram illustrates the relationship between the various toolchains required for the mausVoice environment.
This diagram represents the interaction between the runtime environments and the project's internal architecture.
Sources: llms.txt:30-40, apps/desktop/README.md:40-45
Repository Setup
mausVoice uses a monorepo structure. Initializing the project requires installing dependencies at the root and then navigating to specific workspace applications.
Initial Installation
- Clone the repository.
- Run the root installation command:
pnpm install - For macOS users, a dedicated setup script is provided to automate toolchain verification:
./scripts/setup-macos.sh
Sources: README.md:94-96, scripts/setup-macos.sh:1-10
Workspace Building
Shared packages in packages/ (such as @maus-inc/agent or voice-ai) must be built before they can be consumed by the desktop application.
# Build all workspaces via Turborepo
pnpm run build
# Or filter to build desktop dependencies specifically
pnpm exec turbo run build --filter=desktop^...
Sources: README.md:118, apps/desktop/README.md:21-25, CLAUDE.md:16-20
Running the Application
Because mausVoice relies on native platform features (audio capture, keyboard injection, and system overlays), you MUST use platform-specific commands to start the development server.
Platform-Specific Commands
| Platform | Command |
|---|---|
| macOS | pnpm --filter desktop dev:mac |
| Windows | pnpm --filter desktop dev:windows |
| Linux | pnpm --filter desktop dev:linux |
Note: Do not use pnpm dev or npm run dev directly; native features require the environment variables set by the platform-specific commands.
Sources: README.md:98-105, apps/desktop/README.md:14-18, apps/desktop/package.json:8-12
Environment Variables
Variables can be configured to modify the application's runtime behavior.
VITE_FLAVOR: Sets environment mode (dev,prod,enterprise).MAUSVOICE_ENABLE_DEVTOOLS: Opens browser dev tools on startup.MAUSVOICE_DESKTOP_PLATFORM: Overrides automatic platform detection.
Sources: apps/desktop/README.md:50-57
Quality Control & Bindings
mausVoice uses Specta to generate TypeScript bindings from Rust commands, ensuring type safety across the FFI boundary.
Core Development Scripts
| Task | Command | Description |
|---|---|---|
| Generate Bindings | pnpm gen:bindings | Regenerates bindings.ts from #[tauri::command] definitions. |
| Type Checking | pnpm run check-types | Runs tsc --noEmit across workspaces. |
| Extract i18n | pnpm --filter desktop i18n | Extracts and syncs translation keys. |
| Linting | pnpm run lint | Runs Prettier and oxlint. |
Sources: README.md:118-122, CLAUDE.md:88-95, apps/desktop/package.json:20-25
Data Flow Sequence
The interaction between the TypeScript "Brain" and the Rust "API" during development initialization:
Sources: llms.txt:30-40, CLAUDE.md:26-30
API Configuration
To fully utilize the application during development, API keys for transcription and LLM cleanup must be provided. These are entered in the Settings menu of the application and are stored locally using XChaCha20-Poly1305 encryption.
- Deepgram: Used for streaming transcription (e.g.,
nova-3). - Groq: Used for LLM-based text structure and formatting.
- Local Whisper: If no keys are provided, the app defaults to local transcription via the
rust_transcriptionsidecar.
Sources: README.md:58-62, llms.txt:63-70, CLAUDE.md:33-35
Conclusion
Setting up the mausVoice development environment requires a hybrid toolchain of Node.js and Rust. By adhering to the monorepo structure and utilizing platform-specific dev commands, developers can ensure native capabilities like the recording pill and global hotkeys function correctly. Key maintenance tasks include rebuilding shared packages after changes and regenerating Specta bindings when modifying Rust-to-TypeScript interfaces.