Privacy & Telemetry
Relevant source files
The following files were used as context for generating this wiki page:
MacParakeet is designed as a local-first application where privacy is a core architectural property. The system ensures that speech recognition and data storage remain on-device, while providing an opt-out telemetry and crash reporting system to inform product decisions and improve stability. All core speech-to-text (STT) functions, including dictation and transcription, stay fully offline.
The telemetry architecture is self-hosted on Cloudflare (Workers + D1) to maintain full control over data privacy guarantees. It is strictly non-identifying and session-scoped, meaning no persistent identifiers or personal content such as audio or transcriptions are ever transmitted.
Sources: README.md, spec/adr/012-telemetry-system.md:46-77
Privacy Model & Guarantees
MacParakeet's privacy stance is built on the principle that audio and transcript content never leave the user's Mac. The telemetry system is engineered to be content-free and non-identifying.
Data Sovereignty
- Local STT: Models run on the Apple Neural Engine (ANE) via FluidAudio CoreML. No cloud STT is utilized.
- No Accounts: No registration, email, or login is required to use the application.
- Content Privacy: Transcription text, custom words, file names, URLs, and LLM prompts are never sent to the telemetry server.
- Local Storage: Audio files and the user database (SQLite via GRDB) are stored locally.
Telemetry Privacy Characteristics
The system uses session-scoped telemetry to prevent long-term tracking:
- No Persistent IDs: A new session UUID is generated every time the app launches.
- No Device Fingerprints: No hardware serial numbers or UDIDs are collected.
- No IP Storage: While Cloudflare processes requests, IP addresses are not stored. Location is derived at the country level only via headers.
- Redaction: Server-side regex is employed to strip sensitive information like file paths, URLs, and API keys from error messages before storage.
Sources: README.md, spec/adr/012-telemetry-system.md:46-64, spec/README.md
Telemetry System Architecture
The telemetry system follows a fire-and-forget batching architecture designed to be lightweight and non-blocking.
High-Level Data Flow
The diagram above shows the flow of telemetry data from the local client to the self-hosted Cloudflare backend.
Components
- TelemetryService: Manages the event queue, batching, and network transmission.
- Cloudflare Worker: A serverless endpoint that validates incoming event batches against an allowlist and redacts PII.
- D1 Database: A serverless SQLite database used for storing non-identifying product analytics.
Sources: spec/adr/012-telemetry-system.md:29-44, Sources/MacParakeetCore/Services/Telemetry/TelemetryService.swift
Crash Reporting System
The CrashReporter provides visibility into application failures that would otherwise be silent. It is designed to be async-signal-safe, ensuring that crash data is captured even when the application's runtime is compromised.
Crash Capture Flow
The sequence diagram illustrates the lifecycle of a crash report, from initial signal capture to reporting on the subsequent launch.
Key Features
- Signal Handlers: Registers for critical signals including
SIGSEGV,SIGABRT,SIGBUS, andSIGILL. - Async-Signal Safety: Uses low-level POSIX functions (
open,write,close) and pre-allocated buffers to avoid deadlocks during a crash. - Stack Trace Capture: Records up to 64 frames of the call stack for symbolication.
- Persistence: Reports are saved to
~/Library/Application Support/MacParakeet/crash_report.txtand sent upon the next successful application start.
Sources: plans/completed/2026-03-crash-reporting.md, Sources/MacParakeetCore/Services/Telemetry/CrashReporter.swift
Telemetry Implementation Details
Event Batching and Transmission
The TelemetryService accumulates events in an in-memory queue. Events are flushed to the server under specific conditions:
- The queue reaches a batch size (typically 100 events).
- A 30-second background timer triggers a flush.
- The application is about to terminate (synchronous flush).
| Parameter | Default Value | Description |
|---|---|---|
| Batch Size | 100 | Maximum number of events sent in a single HTTP request. |
| Flush Interval | 30s | Periodic interval for sending queued events. |
| Redaction Limit | 512 chars | Maximum length of error descriptions before truncation. |
Sources: spec/adr/012-telemetry-system.md:46-77, plans/completed/2026-02-telemetry-contract-refactor.md
Event Types
The system tracks approximately 97 different event types across several categories:
- App Lifecycle:
app_launched,app_updated. - Core Operations:
dictation_completed,transcription_operation,meeting_recording_started. - Errors:
crash_occurred,transcription_failed. - System:
permission_denied,model_loaded.
Sources: spec/adr/012-telemetry-system.md:66-77, plans/completed/2026-03-crash-reporting.md
Configuration & Opt-Out
Users can manage their privacy settings through the application's configuration. Telemetry is enabled by default but can be disabled via several methods:
- GUI Settings: Toggling the "Help improve MacParakeet" option in the Privacy card.
- CLI Command:
macparakeet-cli config set telemetry off. - Environment Variables: Setting
MACPARAKEET_TELEMETRY=0or the industry-standardDO_NOT_TRACK=1. - CI Detection: Telemetry is automatically disabled in known CI environments (e.g., GitHub Actions, Jenkins).
Sources: README.md, integrations/README.md
Summary
MacParakeet's Privacy & Telemetry system strikes a balance between user privacy and necessary product observability. By keeping all sensitive audio and text data on-device and utilizing a self-hosted, non-identifying telemetry stack, the project adheres to its local-first philosophy while maintaining the ability to diagnose crashes and understand feature usage.