The Privacy-First, 100% Local AI Copilot & Voice Dictation Workspace for macOS
Flow is a native desktop command center that seamlessly fuses a multi-turn agentic AI chat workspace (Cowork) and instantaneous, push-to-talk disfluency-free dictation refinement (Flow) directly into your daily macOS workflow. Designed with a strict privacy-first philosophy, Flow is engineered to run 100% locally on-device using local voice transcription (Whisper.cpp) and local LLMs (managed llama.cpp, LM Studio, Ollama)—keeping all your voice logs, transcripts, workspace files, and code strictly on your machine, while giving you the full flexibility to connect cloud LLMs and remote transcription APIs as you wish.
A powerful, multi-turn chat workspace powered by LLMs with robust agentic tool-calling capabilities. Check live execution blocks, run custom bash analysis, view auto-refinement states, load skills, and track step-by-step progress via the interactive Todo checklist panel:
Use it in any app! Just press the global hotkey to instantly record, transcribe, and refine text. Features real-time audio statistics, live word counters, inline transcript editing, and instant LLM-powered refinement actions:
Hold a hotkey and speak (or type) a request to the agent in a floating popup — without switching apps. It sees your current screen, can act across apps, asks before each step, and streams the answer right where you're working. Tap the hotkey (instead of holding) to open it with context-aware suggestions:
Just say (or type) things like:
| Intent | Example |
|---|---|
| 🔎 Ask about your screen | "Summarize this page" · "Explain this code" · "What does this error mean?" |
| ✍️ Write & rewrite | "Reply to this email" · "Make this more concise" · "Fix grammar and tone" |
| 🚀 Do things across apps | "Save this as a note" · "Draft a reply in Mail" · "Open this link in my browser" |
| ⚡ Quick answers | "What's 15% of 240?" · "Convert 30°C to °F" · "Define 'idempotent'" |
The same popup flows smoothly through Listening → Transcribing → Thinking → Answer — copy the response, hit + for a new chat, or open in app to continue in the full Cowork window.
A pinwheel status-bar widget that shows live state (idle / recording / transcribing) and one-tap commands. The dropdown lists your active shortcuts and quick actions:
- Hotkey hints — Hold ⌥ Right Option and speak (dictation), Double-tap ⌥ Right Option to fix grammar, and Hold ⌘ Right Command to ask the agent (Quick Ask).
- Open Quick Ask — launches the floating Quick Ask HUD as a plain chat.
- Show Flow — brings the main window to the front.
- Quit Flow — ⌘Q.
| 💻 General & Bash Approvals | 🦙 Local LLM (llama.cpp) |
|---|---|
Configure allowed commands and Python executable paths |
Manage local llama.cpp server and download GGUF models |
| 🎙️ Voice & Transcription Settings | |
Select transcription provider (on-device/cloud) and set global hotkeys |
|
Flow is designed from the ground up to respect your privacy and secure your data:
- Zero Cloud Leakage — Keep all your voice logs, dictation transcripts, workspace files, and agent logs strictly on your local disk.
- On-Device Speech-to-Text — Bundled native
whisper.cpptranscription runs fully offline with zero external API calls. - Managed Local LLM Server — Flow can download, start, stop, and configure a local
llama.cppserver to run open-source GGUF models directly on your Mac. - Opt-In Cloud Flexibility — Complete compatibility with cloud providers (Anthropic Claude, OpenAI, Google Gemini, OpenRouter) if and only if you choose to configure their API keys.
A full-featured, multi-turn chat workspace powered by LLMs with agentic tool-calling capabilities:
- Streaming responses with live token rendering and smooth fading sidebar text overflow.
- File attachments — upload images, PDFs, CSVs, and text documents directly into the conversation.
- Agent Planning & Todo List — multi-step planning loops with
todo_writeintegration for robust execution. - Structured System Prompt — Pi-inspired composable prompt builder that dynamically injects identity, environment context (date, OS, working directory, Python path), tool guidance, safety guardrails, and mode-specific instructions.
- Dynamic Tool use — the agent can autonomously:
- Read, write, and create files (
file_read,file_write) - Execute shell commands with sandboxed approval (
command) - Plan and track multi-step work via a todo list (
todo_write) - Capture screenshots (
screen_capture) - Search the web (
web_search,web_read) - Persist key facts across sessions (
memory_read,memory_write) - Load custom skills into context (
skill_load)
- Read, write, and create files (
- Session management — create, list, load, and delete chat sessions with responsive UI layout.
- Customizable system prompt — edit the base prompt directly from the Toolkit UI (or via
~/.flow/system_prompt.md). Tool guidance, planning rules, safety guardrails, and environment context are automatically composed on every turn. - Smart output truncation — head+tail pattern (4KB) ensures the agent sees both the start and end of long tool outputs.
Record voice notes and transcribe them with configurable speech-to-text providers:
- One-click record/stop with high-quality audio capture (M4A) and real-time listening indicators.
- Text & Voice Switching — flexible input interface allowing you to toggle between typing directly into the transcript area or using the microphone to capture voice.
- Inline Editing with Auto-Save — modify transcriptions directly in the viewport; edits are auto-saved on-blur to ensure a friction-free experience.
- Local STT — bundled
whisper.cpp(fully offline, no API key required). - Cloud STT — OpenAI Whisper, Deepgram.
- Transcript refinement via LLM (streaming):
- Clean — fix grammar, punctuation, and disfluencies
- Summarize — condense to 2-3 sentences
- Bullet points — extract key points
- Custom prompt — your own instruction
- Auto-refine on stop — optionally refine every transcript automatically after recording.
- Transcript library — save, browse, search, and delete past transcriptions.
- Global hotkey (configurable modifier) for instant dictation from any app.
- Double-tap hotkey — grabs selected text and fixes grammar/spelling via LLM.
- Native macOS overlay — visual recording indicator with live status.
- Menu bar icon — pinwheel status indicator (idle / recording / transcribing).
A second, dedicated push-to-talk hotkey that opens a floating, always-on-top popup (the HUD) instead of pasting text. It runs the full Cowork agent right where you are, so you never have to leave your current app.
- Hold to talk, tap for suggestions — hold the configurable hotkey to speak a request; a quick tap opens the HUD with context-aware action chips for what's on screen. Also available from the menu bar (Open Quick Ask).
- One unified popup — the same window flows smoothly from Listening (live waveform, with ✕ cancel / ✓ send) → Transcribing → Thinking (current-step pill) → streamed answer. Pre-warmed so it appears instantly and never steals focus from your current app.
- Acts from on-screen context — reads the frontmost app and your text selection, and attaches a screenshot when the request needs to see the screen (e.g. "summarize this page", "what does this error mean?"). Simple questions skip the screenshot for a fast, lightweight reply.
- Works across apps — can drive other apps via macOS automation (
osascript/open) to gather what it needs and bring the result back. - Approve, then keep working — when a step needs a command, the HUD shows a compact Needs approval card; approve and the agent continues. Cross-app automation is pre-allowed per HUD session so multi-step tasks flow with minimal friction.
- Conversation, not one-shot — type follow-ups in the HUD, copy any response, start a fresh chat with +, or open in app to continue the same session in the full Cowork window.
- Vision-aware suggestions — with an image-capable model, the tap-to-open chips reflect what's actually on your screen; otherwise it falls back to a static capability menu.
What you can ask it:
- Ask about your screen — "Summarize this page", "Explain this code", "What does this error mean?"
- Write & rewrite — "Reply to this email", "Make this more concise", "Fix grammar and tone"
- Do things across apps — "Save this as a note", "Draft a reply in Mail", "Open this link in my browser"
- Quick answers — "What's 15% of 240?", "Convert 30°C to °F", "Define 'idempotent'"
Quick Ask needs Microphone (to talk), Screen Recording (to see the screen), and Accessibility (to read the selection and act across apps). Grant them from Settings → HUD & Quick Ask.
- Skills — reusable instruction sets the agent can load into context at runtime to guide specialized behaviors (customizable via the Toolkit).
- Snippets — trigger/expansion text replacements applied to transcriptions.
- Full CRUD from the Settings/Toolkit UI.
- Managed llama-server — Flow can download, start, and stop a local llama.cpp inference server.
- One-click GGUF download from Hugging Face with progress tracking.
- Model picker — native file dialog for local
.gguffiles. - Auto-detection of served models via
/v1/models.
- Local / OpenAI-compatible — LM Studio, Ollama, llama.cpp, or any
/v1/chat/completionsendpoint. - Anthropic (Claude).
- OpenAI (GPT-4o, etc.).
- Google Gemini.
- OpenRouter.
- Custom cloud endpoint with configurable base URL + API key.
- Automatic provider fallback: primary → fallback → legacy agent config.
- Accessibility & Screen Recording Permissions — Checked and requested natively on macOS with user warnings.
- Microphone Permissions Warning Bar — Displays a clear visual warning banner if microphone access is denied or restricted, with a manual trigger to Open System Settings to resolve.
- Sandboxed Command Execution — Shell commands run by the agent require explicit user approval via a frontend dialog.
- Configurable allow/block lists persisted in
~/.flow/exec-approvals.json(Blocked patterns are automatically denied; allowed patterns are auto-approved).
flow/
├── main.go # Wails app entry point
├── wails.json # Wails project configuration
├── flow.sh # Dev, build, DMG, sign, and utility CLI
├── dequarantine.sh # macOS Gatekeeper quarantine removal
│
├── docs/ # Project documentation and assets
│ └── images/ # Visual screenshots and UI preview gallery
│
├── backend/ # Go backend (Wails-bound)
│ ├── app.go # App struct, Startup/Shutdown lifecycle
│ ├── agentapp.go # Cowork streaming & session CRUD
│ ├── flow.go # Voice recording, transcription, transcript CRUD
│ ├── flow_refine.go # LLM-powered transcript refinement (streaming)
│ ├── dictation.go # System-wide dictation hotkey setup
│ ├── settings.go # Settings load/save, LLM client management
│ ├── models.go # OpenAI-compatible /v1/models listing
│ ├── llama.go # Managed llama.cpp server + GGUF download
│ ├── plugins.go # Skills CRUD (Wails facades)
│ ├── snippets.go # Snippets CRUD (Wails facades)
│ └── internal/
│ ├── agent/ # Agentic loop: multi-turn tool-calling, structured prompt builder
│ ├── config/ # Config bootstrap, load/save, exec approvals
│ ├── llm/ # LLM client abstraction (Anthropic, OpenAI)
│ ├── llamacpp/ # llama-server process manager
│ ├── parser/ # Content parsing utilities
│ ├── plugins/ # Skills store (file-backed)
│ ├── session/ # Session persistence (JSONL-based)
│ ├── snippets/ # Snippets store (file-backed)
│ ├── speech/ # STT (Whisper, Deepgram, local), dictation, menu bar, overlay
│ ├── streaming/ # Stream manager, file attachments, content builder
│ └── tools/ # Tool registry + implementations (file, command, memory, todo, web, skill, screen)
│
├── frontend/ # Svelte + Vite frontend
│ └── src/
│ ├── App.svelte # Root app shell with tab navigation
│ ├── main.js # Svelte mount point
│ ├── app.css # Global styles
│ └── components/
│ ├── CoworkWorkspace.svelte # Cowork agent chat UI
│ ├── FlowPanel.svelte # Voice recorder & transcript viewer
│ ├── FlowRefineMenu.svelte # Refinement action picker
│ ├── AgentWorkspace.svelte # Cowork workspace panel
│ ├── AgentSidebar.svelte # Cowork sidebar panel
│ ├── AgentInfoPanel.svelte # Cowork task info panel
│ ├── AgentFileCard.svelte # File card in Cowork workspace
│ ├── AgentWelcome.svelte # Cowork welcome panel
│ ├── SettingsModal.svelte # Full settings UI
│ ├── SkillToolkitPanel.svelte # Skills & commands manager
│ ├── LoadingSpinner.svelte # Loading indicator
│ └── TypingIndicator.svelte # Chat typing animation
│
└── scripts/
├── sign.sh # Apple code signing, notarization & stapling
├── release.sh # GitHub release automation
├── fetch-llama-server.sh # Download pre-built llama-server binary
└── fetch-whisper-cli.sh # Download pre-built whisper.cpp CLI
- macOS (Apple Silicon or Intel)
- Go 1.24+
- Node.js 18+ and npm
- Wails CLI v2 — install with
go install github.com/wailsapp/wails/v2/cmd/wails@latest
Start the app in live development mode with hot-reloading for the Svelte frontend:
wails devOr use the project script:
./flow.sh dev./flow.sh build
# → build/bin/Flow.app./flow.sh universal./flow.sh dmg
# → build/Flow-Installer.dmg./flow.sh signRequires an Apple Developer account and the signing environment variables configured in scripts/sign.sh.
./flow.sh build && ./flow.sh universal && ./flow.sh dmg && ./flow.sh signCheck if your system has all the Wails development dependencies:
./flow.sh doctorAll configuration lives in ~/.flow/:
| File | Purpose |
|---|---|
config.json |
App settings (providers, API keys, hotkey, STT config) |
system_prompt.md |
Unified editable system prompt (customizable via Toolkit UI) |
exec-approvals.json |
Allowed/blocked shell command patterns |
flow.log |
Application log file |
flow/ |
Saved Flow transcripts (JSON) |
cowork/ |
Cowork session data |
llamacpp/ |
Managed llama-server binary and downloaded GGUF models |
plugins/ |
Skills store |
snippets.json |
Snippets store (JSON) |
memory/ |
Agent persistent memory |
If you are transferring a locally built, unsigned binary between machines and encounter a Gatekeeper quarantine warning, simply remove the attribute via:
xattr -d com.apple.quarantine /Applications/Flow.appMIT License