Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
The MacParakeet development environment is designed for fast, local-first iteration on Apple Silicon Macs. The project utilizes Swift Package Manager (SwiftPM) and Xcode, focusing on a native Swift 6 concurrency-clean codebase that integrates with FluidAudio for on-device speech recognition.
The repository supports two primary products: MacParakeet.app (SwiftUI) and macparakeet-cli (automation surface). Development workflows are optimized for both human developers and AI agents, emphasizing isolated worktrees and automated verification scripts.
Sources: AGENTS.md:7-14, CLAUDE.md:16-24
Prerequisites and Toolchain
MacParakeet requires macOS 14.2+ on Apple Silicon hardware to utilize the Apple Neural Engine (ANE) for speech recognition tasks.
| Component | Requirement / Version |
|---|---|
| Hardware | Apple Silicon Mac (M1+) |
| OS | macOS 14.2+ |
| Swift Tools | 5.9 (Swift 6 language-mode for first-party code) |
| Toolchain | Xcode 16.1+ |
| Dependencies | Homebrew-managed ffmpeg and yt-dlp |
Sources: AGENTS.md:32-33, plans/active/2026-06-15-dx-format-lint-baseline.md:27-28, plans/active/cli-as-canonical-parakeet-surface.md:144-148
Project Architecture for Developers
The codebase is partitioned into modules to separate concerns and facilitate testing without a GUI.
Module Boundaries
- MacParakeetCore: Owns shared logic (STT, Database, TextProcessing). It is Swift 6 concurrency clean and contains no SwiftUI views.
- MacParakeetViewModels: Contains
@Observableview models that are testable in isolation from the GUI. - CLI: Public automation surface and developer tool located in
Sources/CLI/. - MacParakeet: The SwiftUI macOS application.
Sources: AGENTS.md:34-40, CLAUDE.md:19-22
Data and Storage
Development environments rely on local persistence:
- Database: GRDB repositories for SQLite access, typically one repository per table.
- User Data: Meeting artifacts and the user database are treated as high-priority user data and should not be deleted during normal recovery/discard flows.
Sources: AGENTS.md:41-42, 49-50
Development Workflow
Developers and agents are encouraged to follow a "check, build, test" cycle using provided scripts.
Build and Execution Commands
Primary commands for local development:
# Build the project
swift build
# Run focused tests
swift test --filter TextProcessingPipelineTests
# Run the developer check script (debug build + tests + lint)
scripts/dev/check.sh [TestFilter]
# Launch the app from source
scripts/dev/run_app.sh
# Execute the CLI for health checks
swift run macparakeet-cli health
Sources: AGENTS.md:21-29, plans/active/2026-06-15-dx-format-lint-baseline.md:112-124
Linting and Formatting
Style enforcement is managed via swift-format and .editorconfig.
- Format Script:
scripts/dev/format.shreformatsSources/andTests/using the.swift-formatJSON configuration. - Linting:
scripts/dev/check.shincludes a report-onlyswift-format lintpass to identify style violations without modifying code.
Sources: plans/active/2026-06-15-dx-format-lint-baseline.md:88-110
Logic Flow: Developer Inner Loop
The following diagram illustrates the recommended inner-loop cycle for developing features or fixes:
This flow ensures that work is based on the latest origin/main and passes all local verification before submission.
Sources: AGENTS.md:21-27, CLAUDE.md:65-74, spec/10-ai-coding-method.md:73-82
Worktree Management
To avoid SwiftPM/Xcode state corruption, the project uses multiple parallel worktrees.
- Base Branching: Always base new branches or worktrees on
origin/mainrather than localmain. - Isolation: Build and test specifically from the worktree that owns the branch to prevent cross-contamination of
.buildfolders. - Ignored Paths: Avoid manual inspection of generated directories like
.build*,.claude/worktrees, ordist.
Sources: AGENTS.md:24-30, CLAUDE.md:92-94
Testing Strategy
MacParakeet distinguishes between standard tests and high-risk area verification.
Test Categories
| Risk Level | Focus Areas | Recommended Verification |
|---|---|---|
| Standard | General logic, ViewModels | swift test --filter <Target> |
| High Risk | Audio capture, persistence, migrations, CLI contracts, privacy, concurrency | swift test (full suite) + scripts/dev/ci_local.sh |
Sources: AGENTS.md:52-54, spec/10-ai-coding-method.md:84-91
Execution Sequence: Feature Verification
Conclusion
The MacParakeet development setup prioritizes Apple Silicon native performance and local-first data integrity. By utilizing structured worktrees, Swift 6 concurrency, and a suite of development scripts, the environment provides a robust framework for iterating on both GUI and CLI components while maintaining high standards for code quality and privacy.
Sources: AGENTS.md:44-48, CLAUDE.md:28-34