/docs/architecture
Architecture
How Talkie's processes fit together. Each one does one job, which keeps capture, UI, and the iPhone bridge easy to reason about.
System Overview
Talkie splits work across a few processes so a crash in transcription does not take down the UI, microphone permission stays with the helper that records, and capture can keep running after you close the main window.
Talkie is the orchestrator: UI, workflows, and data. TalkieAgent is the always-on companion: mic, keyboard, and the local transcription runtime. TalkieServer is a Bun HTTP process that TalkieAgent supervises for the iPhone. There is no standalone TalkieEngine app.
Components
Each component has a clear responsibility and communicates through well-defined interfaces.
Talkie
Main Application (Swift/SwiftUI)
- -User interface and settings
- -Workflow orchestration and execution
- -Data management (GRDB database)
- -Process lifecycle management for helpers
TalkieAgent
Always-on capture + engine host (Swift)
- -Microphone capture and live dictation
- -Keyboard insertion and global hotkeys
- -In-process transcription via TalkieEngineCore
- -Supervises TalkieServer when the iPhone bridge is on
TalkieServer
iOS bridge (TypeScript/Bun)
- -HTTP API for the iPhone app
- -Device pairing and authentication
- -Voice recording ingest from iPhone and Apple Watch
- -Tailscale or loopback transport, never a Talkie cloud
TalkieEngineCore
Embedded runtime (not a process)
- -Whisper and Parakeet transcription inside TalkieAgent
- -Model download, cache, and Metal acceleration
- -Caller-specified priority for live vs batch work
- -Optional WebSocket bridge only when remote engine access is on
Models
Talkie keeps two catalogs. Speech-to-text engines turn recorded audio into text. Language models rewrite, summarize, and run workflows. They are not interchangeable. The Compose header picker is a language-model picker. Live dictation does not use it.
Speech-to-text
Live dictation on Mac uses Parakeet v3 (FluidAudio) inside TalkieAgent. That path is on-device. The hotkey does not offer a model menu.
Retranscribe, on a saved recording, offers a short menu. Apple Speech is a capture fallback, not the Mac hotkey engine. The engine can install other Whisper sizes; those sizes are not on the retranscribe menu.
| Surface | Engine | Id | Notes |
|---|---|---|---|
| Live dictation | Parakeet v3 | parakeet:v3 | On-device. Locked for the Mac hotkey path. |
| Retranscribe | Parakeet v3 | parakeet:v3 | 25 languages, fast. Default on the menu. |
| Retranscribe | Parakeet v2 | parakeet:v2 | English, most accurate Parakeet. |
| Retranscribe | Whisper Small | whisper:openai_whisper-small | On-device WhisperKit. Balanced. |
| Retranscribe | Whisper Large V3 | whisper:distil-whisper_distil-large-v3 | On-device. Best quality on the menu. |
| iPhone fallback | Apple Speech | apple_speech | Used when Parakeet is not ready. Not the Mac hotkey engine. |
Whisper Tiny and Base remain installable in the engine inventory. They are not on the retranscribe menu. Parakeet 110M and Parakeet JA are also installable; they are not on that menu either.
Language models
Compose, workflows, and other rewrite actions read the catalog in LLMConfig.json, plus Apple Intelligence when Foundation Models is available on the Mac. Cloud providers need an API key in Settings. The Compose header currently opens a nested macOS menu of these models, grouped by provider.
| Provider | Recommended models | Default |
|---|---|---|
| Apple Intelligence | Apple Intelligence (On-Device) | When Foundation Models is available |
| OpenAI | GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna | GPT-5.6 Sol |
| Anthropic | Claude Sonnet 5, Claude Opus 5, Claude Fable 5.1, Claude Haiku 4.5 | Claude Sonnet 5 |
| Google Gemini | Gemini 2.5 Flash, Gemini 2.5 Flash Lite, Gemini 2.5 Pro | Gemini 2.5 Flash |
| Groq | Llama 3.3 70B, Llama 3.1 8B Instant | Llama 3.1 8B Instant |
| OpenRouter | Dynamic model discovery (OpenAI, Anthropic, Gemini, DeepSeek, etc.) | Configurable |
Talkie also supports OpenRouter dynamic fetching and custom AI gateways for agents, as well as borrowing models through TalkieServer when the iPhone bridge is active.
XPC Communication
XPC is Apple's process-to-process channel. Talkie uses it to talk to TalkieAgent (capture, dictation, bridge control) and TalkieSync (CloudKit memos). Transcription stays inside TalkieAgent.
When you start a dictation, TalkieAgent captures audio, transcribes it in-process with TalkieEngineCore, and inserts the text. The main app never needs microphone or accessibility permission for that path. Talkie hears about the new dictation over XPC (with a polling fallback if the connection drops).
Process Lifecycle
launchd owns the helper processes. The important split:
- TalkieAgent is always-on — KeepAlive, independent of the main window
- TalkieServer follows Agent — starts and stops with the companion, not with Talkie.app
- TalkieSync attaches to Talkie — CloudKit bridge for memos
- Automatic restart — If Agent crashes, launchd brings it back
In Activity Monitor you should see Talkie and TalkieAgent. TalkieServer appears when the iPhone bridge is on. You should not see a standalone TalkieEngine process.