From 40b4917d75e98f467405d3096e068f5f8ecd742e Mon Sep 17 00:00:00 2001
From: Vlad Gerasimov <vlad@vlad.studio>
Date: Mon, 28 Jul 2025 18:08:48 +0400
Subject: [PATCH] add CLAUDE.md

---
 CLAUDE.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9388408
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+**Prerequisites:**
+- [Rust](https://rustup.rs/) (latest stable)
+- [Bun](https://bun.sh/) package manager
+
+**Core Development:**
+```bash
+# Install dependencies
+bun install
+
+# Run in development mode
+bun run tauri dev
+# If cmake error on macOS:
+CMAKE_POLICY_VERSION_MINIMUM=3.5 bun run tauri dev
+
+# Build for production
+bun run tauri build
+
+# Frontend only development
+bun run dev        # Start Vite dev server
+bun run build      # Build frontend (TypeScript + Vite)
+bun run preview    # Preview built frontend
+```
+
+**Model Setup (Required for Development):**
+```bash
+# Create models directory
+mkdir -p src-tauri/resources/models
+
+# Download required VAD model
+curl -o src-tauri/resources/models/silero_vad_v4.onnx https://blob.handy.computer/silero_vad_v4.onnx
+```
+
+## Architecture Overview
+
+Handy is a cross-platform desktop speech-to-text application built with Tauri (Rust backend + React/TypeScript frontend).
+
+### Core Components
+
+**Backend (Rust - src-tauri/src/):**
+- `lib.rs` - Main application entry point with Tauri setup, tray menu, and managers
+- `managers/` - Core business logic managers:
+  - `audio.rs` - Audio recording and device management
+  - `model.rs` - Whisper model downloading and management  
+  - `transcription.rs` - Speech-to-text processing pipeline
+- `audio_toolkit/` - Low-level audio processing:
+  - `audio/` - Device enumeration, recording, resampling 
+  - `vad/` - Voice Activity Detection using Silero VAD
+- `commands/` - Tauri command handlers for frontend communication
+- `shortcut.rs` - Global keyboard shortcut handling
+- `settings.rs` - Application settings management
+
+**Frontend (React/TypeScript - src/):**
+- `App.tsx` - Main application component with onboarding flow
+- `components/settings/` - Settings UI components
+- `components/model-selector/` - Model management interface
+- `hooks/` - React hooks for settings and model management
+- `lib/types.ts` - Shared TypeScript type definitions
+
+### Key Architecture Patterns
+
+**Manager Pattern:** Core functionality is organized into managers (Audio, Model, Transcription) that are initialized at startup and managed by Tauri's state system.
+
+**Command-Event Architecture:** Frontend communicates with backend via Tauri commands, backend sends updates via events.
+
+**Pipeline Processing:** Audio → VAD → Whisper → Text output with configurable components at each stage.
+
+### Technology Stack
+
+**Core Libraries:**
+- `whisper-rs` - Local Whisper inference with GPU acceleration
+- `cpal` - Cross-platform audio I/O  
+- `vad-rs` - Voice Activity Detection
+- `rdev` - Global keyboard shortcuts
+- `rubato` - Audio resampling
+- `rodio` - Audio playback for feedback sounds
+
+**Platform-Specific Features:**
+- macOS: Metal acceleration for Whisper, accessibility permissions
+- Windows: Vulkan acceleration, code signing
+- Linux: OpenBLAS + Vulkan acceleration
+
+### Application Flow
+
+1. **Initialization:** App starts minimized to tray, loads settings, initializes managers
+2. **Model Setup:** First-run downloads preferred Whisper model (Small/Medium/Turbo/Large)
+3. **Recording:** Global shortcut triggers audio recording with VAD filtering
+4. **Processing:** Audio sent to Whisper model for transcription
+5. **Output:** Text pasted to active application via system clipboard
+
+### Settings System
+
+Settings are stored using Tauri's store plugin with reactive updates:
+- Keyboard shortcuts (configurable, supports push-to-talk)
+- Audio devices (microphone/output selection)
+- Model preferences (Small/Medium/Turbo/Large Whisper variants)
+- Audio feedback and translation options
+
+### Single Instance Architecture
+
+The app enforces single instance behavior - launching when already running brings the settings window to front rather than creating a new process.
\ No newline at end of file