Introduction & Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
MacParakeet is a local-first, privacy-focused voice application designed specifically for Apple Silicon Macs. It provides a high-performance speech-to-text (STT) pipeline using NVIDIA's Parakeet TDT 0.6B models accelerated by the Apple Neural Engine (ANE) via the FluidAudio CoreML wrapper. The project offers both a SwiftUI-based macOS application and a semver-stable Command Line Interface (macparakeet-cli) intended for automation and AI agent integrations. Sources: AGENTS.md:7-13, spec/README.md:5-9, plans/active/cli-as-canonical-parakeet-surface.md:14-18
The system is architected to prioritize on-device processing, ensuring that audio and transcripts remain local by default. While it supports optional cloud-based LLM providers for text transformation and summarization, its core value proposition is high-speed, offline transcription with approximately 155x realtime performance and a low Word Error Rate (WER) of ~2.5%. Sources: AGENTS.md:73-77, spec/README.md:104-108, plans/active/cli-as-canonical-parakeet-surface.md:59-63
Project Architecture
The MacParakeet ecosystem is built upon MacParakeetCore, a Swift library that encapsulates the STT logic, database persistence, and LLM integrations. This core library powers two primary consumers: the GUI application and the CLI.
The CLI serves as the foundation for the product, with the SwiftUI app acting as one well-crafted client. Sources: plans/active/cli-as-canonical-parakeet-surface.md:65-80, AGENTS.md:15-20
Key Components
| Component | Responsibility | Source File |
|---|---|---|
MacParakeetCore | Shared logic for STT, DB access, and LLM orchestration. No SwiftUI dependencies. | AGENTS.md:43-45 |
macparakeet-cli | Public automation surface with stable JSON output and semver contracts. | plans/active/cli-as-canonical-parakeet-surface.md:92-100 |
MacParakeet.app | SwiftUI-based user interface for dictation and meeting recording. | AGENTS.md:17 |
Database | SQLite persistence using GRDB repositories (one per table). | AGENTS.md:50-51 |
FluidAudio | CoreML/ANE Swift wrapper for Parakeet models. | spec/README.md:104-106 |
Getting Started for Developers
Developers working on the repository should adhere to the Swift 6 language mode and concurrency-clean patterns. The project utilizes Swift Package Manager (SPM) for dependency management and builds. Sources: AGENTS.md:41-43
Build and Test Commands
Standard workflows for building and verifying the project are as follows:
# Build the project
swift build
# Run all tests
swift test
# Run focused tests for the text processing pipeline
swift test --filter TextProcessingPipelineTests
# Run local CI checks and formatting
scripts/dev/check.sh
scripts/dev/format.sh
# Run the GUI application for development
scripts/dev/run_app.sh
Sources: AGENTS.md:23-31, CLAUDE.md:87-94
Working Method for Agents
AI Coding Agents (such as Claude Code) are instructed to follow a specific hierarchy for the "Source of Truth" to prevent drift:
- Accepted ADRs in
spec/adr/ - Narrative specs listed in
spec/README.md - Active plans (when executing a specific task)
- Current code and tests
Sources: spec/10-ai-coding-method.md:20-27, CLAUDE.md:38-45
AI Agent Integration
MacParakeet positions its CLI as the "canonical Parakeet-on-Apple-Silicon surface" for agents like OpenClaw and Hermes. The CLI provides a reliable contract for local STT, which is often a missing gap in agent stacks that otherwise rely on cloud APIs. Sources: plans/active/cli-as-canonical-parakeet-surface.md:14-25
CLI Capabilities for Agents
- Stable JSON Output: Every read-only command supports
--jsonfor machine readability. Sources: plans/active/cli-as-canonical-parakeet-surface.md:92-100 - Persistent Memory: Access to the SQLite database allows agents to recall prior dictations or prompt outputs. Sources: plans/active/cli-as-canonical-parakeet-surface.md:20-22
- Predictable Exit Codes: 0 for success, non-zero for failures, with errors directed to stderr. Sources: plans/completed/2026-06-19-boundary-contracts.md:154-160
AI & LLM Setup
While STT is local, AI features (Summaries, Chat, Ask) require a provider configuration. MacParakeet supports three primary paths for AI:
- Local AI Apps: Recommended path using LM Studio or Ollama (detected via local endpoints).
- API Keys: Cloud providers like Anthropic, OpenAI, or OpenRouter.
- Local CLI: Advanced path for running command-line AI tools.
Sources: plans/active/2026-05-ai-setup-ux.md:46-60, spec/README.md:109-111
AI Readiness States
The system tracks AI configuration via a readiness model to avoid speculative background probing:
- Set Up Needed: No configuration exists.
- Ready: Configured and the last attempt succeeded.
- Can't Connect: Configured, but the last attempt failed (e.g., local server is down).
Sources: plans/active/2026-05-ai-setup-ux.md:104-115
Summary
MacParakeet provides a robust, private foundation for voice interactions on macOS. By combining the efficiency of the Apple Neural Engine with a semver-stable CLI and a modular Swift architecture, it serves both end-users seeking privacy and developers building autonomous agent workflows. Successful development requires adherence to the established spec-first working method and maintaining the local-first posture. Sources: AGENTS.md:7-13, spec/10-ai-coding-method.md:8-12