calliope/CLAUDE.md

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

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