/docs/overview
Overview
Talkie lets you talk to your Mac instead of typing. It runs locally and syncs across your devices without a Talkie cloud.
Philosophy
Three principles shape how Talkie is built. These aren't marketing words. They show up in how the app actually works.
Local-First
Your voice data never leaves your devices. All transcription happens on your Mac.
Privacy by Design
No cloud processing required. No accounts needed. Your data is yours.
Transparent
See exactly what's happening. No black boxes or hidden processes.
Design Principles
We figure anyone using this might want to poke at it. So you can see and change everything, with defaults good enough that you rarely have to.
Everything is a file
Your data lives in readable formats on disk. SQLite databases, JSON exports, audio files—all accessible and portable.
Small, focused data stores
Instead of one monolithic database, each component owns its data. Memos in one place, live dictations in another. Clear boundaries, easy to reason about.
Data stores exposed by default
We don't hide your data in opaque containers. Browse your recordings, query your databases, export anything. Your data, your access.
Well-defined lifecycles
Every recording flows through clear phases: capture → transcription → routing → storage. Each phase has hooks where you can plug in custom logic.
Protect the critical path
Recording and transcription are sacred. Nothing gets to block them: not sync, not workflows, not UI rendering. The happy path stays fast.
Smart defaults, full control
Talkie works out of the box. But when you want to change something (workflows, shortcuts, data locations, export formats), it's all configurable.
Local-First Design
"Local-first" means your data lives on your device first, always. The cloud is optional, not required. This has real implications:
- Works offline — Record, transcribe, and create memos without internet
- Instant startup — No waiting for cloud connections or sync
- You own your data — It's in readable formats on your disk
- No accounts required — Start using Talkie immediately
When you do enable sync (like iCloud), it's additive. The app works fine without it; sync just keeps your devices matched up.
Multi-Process Architecture
Talkie is two macOS apps plus a local HTTP bridge. Capture and transcription live in TalkieAgent so the main window can quit without taking the mic down with it.
Why split the work?
- Fault isolation — A crash in transcription does not take down the UI
- Permission boundaries — Microphone, accessibility, and screen capture stay with TalkieAgent
- Always-on capture — TalkieAgent stays running when Talkie is closed
- Local engine — Whisper and Parakeet run in-process inside TalkieAgent, not as a third app
How Components Communicate
Native macOS pieces talk over XPC. The iPhone talks to a local HTTP process that TalkieAgent supervises.
XPC (Inter-Process Communication)
XPC is Apple's process-to-process channel: typed messages, sandboxing, and launchd lifecycle. Talkie uses it to talk to TalkieAgent for capture control, dictation events, and the local HTTP bridge. CloudKit memo sync uses a second XPC connection to TalkieSync. Local transcription does not cross a third process. TalkieEngineCore runs inside TalkieAgent.
HTTP (Local Server)
TalkieAgent supervises TalkieServer, a local Bun process. The iPhone app talks to that process over HTTP. Traffic stays on your devices: Tailscale by default, or loopback for local-only development.
Continue Reading
Ready to go deeper? The architecture docs explain each component in detail.
Detailed look at each component and how they work together