Initial commit: Calliope voice-to-text macOS menu bar app

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -0,0 +1,86 @@
+# Calliope
+
+Voice-to-text for macOS — speak and type into any app.
+
+Calliope sits in your menu bar, listens when you hold a hotkey, transcribes your speech with Whisper, and types the result into whatever app is focused. No cloud, no API keys — everything runs locally on your Mac.
+
+## Installation
+
+```bash
+git clone https://github.com/yourname/calliope.git
+cd calliope
+pip install -e .
+```
+
+## Usage
+
+```bash
+# First run — launches the setup wizard, then starts the app
+calliope
+
+# Re-run the setup wizard
+calliope setup
+
+# Launch with overrides
+calliope --device 2 --model openai/whisper-large-v3 --debug
+
+# Print version
+calliope --version
+```
+
+## Hotkeys
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| Push-to-talk | `Ctrl+Shift` (hold) | Records while held, transcribes on release |
+| Toggle | `Ctrl+Space` | Start/stop recording |
+
+Hotkeys are configurable via the setup wizard or `~/.config/calliope/config.yaml`.
+
+## Permissions
+
+Calliope needs two macOS permissions:
+
+- **Accessibility** — to type text into other apps (System Settings > Privacy & Security > Accessibility)
+- **Microphone** — to record audio (System Settings > Privacy & Security > Microphone)
+
+The setup wizard checks for these and can open System Settings for you.
+
+## Configuration
+
+Config lives at `~/.config/calliope/config.yaml`:
+
+```yaml
+device: null          # sounddevice index; null = system default
+model: distil-whisper/distil-large-v3
+hotkeys:
+  ptt: ctrl+shift
+  toggle: ctrl+space
+context: ""           # domain-specific terms to help Whisper
+debug: false
+```
+
+CLI flags override config values for that session.
+
+## Troubleshooting
+
+**"Status: Model load failed"**
+Check that you have enough disk space and RAM. The default model needs ~1.5 GB. Run with `--debug` for detailed logs.
+
+**No text appears after transcribing**
+Make sure Accessibility permission is granted. Restart Calliope after granting it.
+
+**Wrong microphone**
+Run `calliope setup` to pick a different input device, or set `device` in the config file. Use `python -m sounddevice` to list devices.
+
+**Hotkeys not working**
+Ensure no other app is capturing the same key combo. Customize hotkeys via `calliope setup`.
+
+## Remaining TODOs
+
+- LICENSE file
+- Unit tests
+- CI/CD pipeline
+- Homebrew formula
+- `.app` bundle for drag-and-drop install
+- Changelog