# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What is Calliope?

A macOS menu bar app for local voice-to-text. Users press a hotkey, speak, and transcribed text is typed into the focused app. Runs entirely offline using Whisper models via `mlx-whisper`, natively accelerated on Apple Silicon.

## Setup & Running

```bash
pip install -e .        # Install in dev mode
calliope                # Launch (runs setup wizard on first run)
calliope setup          # Re-run setup wizard
calliope --debug        # Launch with debug logging
calliope --device 2 --model mlx-community/whisper-large-v3  # Override config
```

No test suite or linter is configured yet.

## Architecture

**Entry point:** `calliope/cli.py` → Click CLI → `calliope/app.py:main()`

**Data flow:** Hotkey press → Record audio → Transcribe with Whisper → Type into focused app

Key modules in `calliope/`:

- **app.py** — `CalliopeApp(rumps.App)`: main orchestrator, manages menu bar UI and coordinates all components; includes auto-stop-on-silence logic (background thread monitors RMS energy and stops recording after `silence_timeout_seconds` of quiet)
- **recorder.py** — Audio capture via `sounddevice` at 16kHz mono float32, with chunk consolidation
- **transcriber.py** — Whisper STT using `mlx-whisper` (`mlx_whisper.transcribe`); default model `mlx-community/whisper-large-v3-turbo`
- **hotkeys.py** — `HotkeyListener` using `pynput`: supports push-to-talk (Ctrl+Shift hold) and toggle (Ctrl+Space) modes
- **typer.py** — Outputs text via Quartz CGEvents (character mode) or clipboard paste (Cmd+V)
- **overlay.py** — `WaveformOverlay`: floating NSPanel with scrolling waveform during recording, pulsing dots during transcription
- **setup_wizard.py** — Rich-based interactive first-run config (mic, hotkeys, model download)
- **config.py** — Loads/saves YAML config at `~/.config/calliope/config.yaml`

## Platform Constraints

- **macOS only** — uses `pyobjc` bindings (Quartz, AppKit, AVFoundation, ApplicationServices)
- **Apple Silicon required** — `mlx-whisper` uses the MLX framework, which only runs on Apple Silicon (M1 or later)
- Requires Accessibility and Microphone permissions in macOS System Settings