Ora

Privacy-first macOS voice assistant powered by on-device AI

Download • Documentation • Contributing

Ora is a local-first macOS voice assistant that focuses on a small set of high-value workflows: Calendar, Reminders, Contacts, and minimal safe system actions.

The v2 direction is intentionally subtractive: keep the assistant fast, reliable, auditable, and private instead of growing into a broad automation platform. Legacy v1 planning material is archived under docs/legacy/v1/.

Voice or text input
    ↓
Parakeet ASR / typed request
    ↓
Local MLX LLM structured output
    ↓
Core action host + confirmation gates
    ↓
Overlay answer + optional Kokoro TTS + audit record

https://github.com/benedict2310/ora/assets/demo.mp4

Note: Video shows Ora managing calendar events via voice commands.

• 🔒 Local-first by default — Speech recognition, reasoning, and speech synthesis run on-device.
• 🎤 Push-to-talk — Hotkey activation (⌥Space) with menu bar control.
• ⚡ Streaming voice loop — Live transcription, structured reasoning, and optional spoken responses.
• 🗓 Calendar actions — Query schedules, find slots, and propose confirmed mutations.
• ✅ Reminders actions — List, create, update, complete, and delete reminders with guardrails.
• 👥 Contacts lookup — Resolve people for lookup and invitation workflows.
• 🖥 Minimal system actions — Open apps, URLs/searches, and relevant settings.
• 📝 Audit trail — Mutations answer what changed, when, why, and whether the user confirmed.
• 📈 Local telemetry — Conversation flow, latency, cancellation, TTS/STT, and barge-in behavior are observable without logging private content.
• 🔄 Auto-updates — Signed release builds update via Sparkle.

Out of v2 core: mail, messages, notes, skills/scripts, semantic memory, research/background agents, vision, and cloud-provider routing. See docs/product/pdrs/ for accepted product decisions.

Latest Release: Ora (Releases)

1. Download Ora-{version}.dmg from Releases
2. Open the DMG and drag Ora.app to Applications
3. Launch Ora and grant requested permissions
4. Press ⌥Space to activate

Note: Sparkle auto-updates are intended for the signed release build installed in /Applications. Developer builds disable update checks.

1. Download from Releases
2. Install and launch
3. On first run, Ora downloads required on-device models (ASR + LLM + TTS)
4. Grant permissions when prompted:
   • Microphone — Voice input
   • Calendar — Event management
   • Reminders — Task management
   • Contacts — Contact lookup
   • Accessibility — Global hotkey if required by the current build
5. Press ⌥Space and start talking

# Install dependencies
brew install xcodegen

# Clone repository
git clone https://github.com/benedict2310/ora.git
cd ora

# Build and run
./build.sh run

Build Commands:

Ora v2 is organized around a small local assistant loop:

1. Input → push-to-talk or typed text
2. ASR → FluidAudio Parakeet for speech-to-text
3. LLM → MLX Swift local model with compact structured output
4. Actions → Calendar, Reminders, Contacts, and minimal System adapters
5. Confirmation → required before state-changing actions
6. TTS/UI → Kokoro speech output and compact overlay
7. Audit + telemetry → local mutation history and debuggable per-turn traces

Tech Stack:

• Language: Swift 6.0 with strict concurrency
• Frameworks: AppKit, SwiftUI, AVFoundation, EventKit, Contacts, OSLog
• ML Runtime: MLX Swift for on-device inference
• Build System: XcodeGen for project generation

See docs/ for current product and architecture docs.

The repository is mid-migration. Current code still includes legacy directories until the v2 phases remove or quarantine them.

Current tree highlights:

Ora/
├── Ora/                    # Main app source during migration
│   ├── ASR/                # Speech recognition
│   ├── Audio/              # Audio capture and VAD
│   ├── LLM/                # Local language model runtime
│   ├── Orchestration/      # Existing app flow to be replaced by v2 Interaction
│   ├── Tools/              # Existing tool implementations; v2 will register only core actions
│   ├── TTS/                # Text-to-speech runtime
│   └── UI/, Overlay/, Preferences/
├── OraTests/               # Existing app tests during migration
├── docs/                   # Current v2 docs plus legacy archive
│   ├── architecture/
│   ├── product/
│   └── legacy/v1/
├── scripts/                # Build and release scripts
├── project.yml             # XcodeGen configuration
└── build.sh                # Build helper script

The target v2 layout is documented in docs/architecture/v2-shape-and-migration-plan.md. New v2 code should move toward App/, Interaction/, Actions/, Telemetry/, ModelRuntime/, Data/, and focused OraCoreTests/ as those phases land.

./build.sh test

The default gate is intentionally fast and high-signal. Use named commands for slower legacy, permission, model, audio, or Thread Sanitizer checks.

View live logs:

./build.sh logs

View a specific category:

./build.sh logs --category telemetry

Ora v2 telemetry should expose non-sensitive fields such as event names, turn IDs, durations, counts, action names, and result categories as visible/public log fields. Transcript text, prompts, audio, contact data, calendar/reminder content, URLs, and raw tool payloads must be omitted or private by default.

If permissions stop working after rebuild:

./build.sh reset-perms

macOS TCC tracks permissions by bundle ID + code hash. Every rebuild changes the hash, so local development builds may need a reset and re-grant.

Contributions are welcome. Please keep changes aligned with the accepted v2 scope in docs/product/ and docs/architecture/.

Areas where we'd love help:

• 🐛 Bug fixes and performance improvements
• 📝 Documentation and examples
• 🎨 Focused UI/UX improvements
• 🧪 High-signal tests for core contracts and supported workflows

1. Fork the repository
2. Create a feature branch: git checkout -b feat/amazing-feature
3. Make your changes
4. Run tests: ./build.sh test
5. Commit: git commit -m "feat: add amazing feature"
6. Push: git push origin feat/amazing-feature
7. Open a Pull Request

Ora is source available — you can read and audit the code, but redistribution and commercial use require explicit written permission. See LICENSE for full terms.

© 2026 Benedict Evert / Futurelab Studio. All rights reserved. Contact: [email protected]

Built with these amazing open-source projects:

• MLX Swift — Apple Silicon ML framework
• FluidAudio — Streaming ASR
• Sparkle — Auto-update framework
• Qwen — Local language models
• Kokoro TTS — Text-to-speech