flowcode 🔊 — the voice of Claude Code

Talk to Claude. Hear it talk back. In English or Czech. Fully local, on your Mac.

---

Kick off a task, then go do something else. flowcode is a tiny native macOS menu-bar app that gives Claude Code — and the Claude desktop app (Chat, Cowork, Code) — a voice: it reads each new reply aloud the moment it lands (local Kokoro TTS), so you hear when Claude finishes, asks a question, or needs your call — without babysitting the terminal. When it's your turn, hold Right Option (⌥) and talk (local Whisper STT); your words are pasted in, and you press Enter. A Jarvis-style orb pulses while it speaks.

The only truly Mac-native, voice-first companion for Claude Code: read-aloud and dictation — no Electron, no cloud, no account, no freemium. Claude runs completely unmodified; flowcode just sits beside it. English out of the box; Czech one click away.

Why you'll want this

• 👂 Stop watching the scrollback. Claude works while you do something else; the reply is spoken the instant it arrives — tool calls and code blocks skipped, so you hear the answer, not the plumbing — and you come back exactly when you're needed.
• 🎙️ Talk instead of type, safely. Hold Right Option, speak, release → transcribed locally and pasted into whatever's focused (terminal, editor, the Claude desktop app). It never presses Enter — you stay in control of every commit.
• 🔒 Fully on-device, private. Kokoro TTS + Whisper STT run on localhost — your voice and Claude's words never leave your Mac (verifiable with lsof / Little Snitch). No telemetry, no account, no plugin.

Honest scope: this is read-aloud + push-to-talk dictation today — a voice layer, not hands-free barge-in conversation (yet). Install is build-from-source (scripts/setup.sh) — there's no prebuilt one-click download yet.

What it does

• 🔊 Read-aloud — every new assistant message is spoken via local Kokoro TTS, with the orb pulsing to the speech. Tool-call narration and code blocks are skipped — you hear the prose, not the plumbing.
• 🎙️ Push-to-talk dictation — hold Right Option (⌥), speak, release. Your words are transcribed by local Whisper and pasted into whatever app is focused (your terminal, an editor, the Claude desktop app, anywhere). It never presses Enter — you commit.
• 💻 Claude Code and Claude Desktop — reads the Claude desktop app's replies aloud too (Chat, Cowork, Code), and dictates into it. Choose Listen to ▸ Claude Code / Claude Desktop / Both.
• 🌍 English & Czech — Language ▸ English / Čeština. Czech read-aloud uses an on-demand neural voice that downloads only when you ask for it; English never downloads anything.
• 🗜️ Read-aloud modes — Read replies ▸ Off / Full / Compact. Compact speaks just the gist (first + last sentence) when a reply runs long.
• ⏯️ Pause / Resume the whole voice layer with ⌃⌥Space or the menu — the mic is released the moment you're not dictating.
• ✦ Orb HUD — a luminous, audio-reactive orb that shows when flowcode is listening, speaking, or idle.
• ⚡ Local-first & private — TTS and STT are localhost services; nothing is sent to the cloud.

Works with

🤖 Claude Code	Any session, completely unmodified — flowcode reads the transcript it already writes.
💻 Claude Desktop	Reads Chat / Cowork / Code replies aloud (via the Accessibility tree) and dictates into them.
🗣️ Kokoro TTS	Local English text-to-speech (127.0.0.1:8880) — read-aloud, with a pickable voice.
🇨🇿 Czech (optional)	On-demand neural voice (Coqui VITS) + multilingual Whisper — downloaded only when you pick Czech.
✍️ Whisper STT	Local speech-to-text (127.0.0.1:2022) — push-to-talk dictation, English & Czech.
🖥️ macOS 14+	Apple Silicon (M-series). Menu-bar agent, no Dock icon.
⌨️ Your terminal / editor	Warp, Terminal, iTerm2, VS Code… dictation pastes into the focused app.

Install

flowcode is installed by an AI coding agent (Claude Code) — there's intentionally no prebuilt download. The agent handles the whole setup: voice services, build, and walking you through the two macOS permission toggles. Requires macOS 14+ on Apple Silicon (the local TTS stack has no Intel builds) and the Xcode 16+ Command Line Tools (Swift 6).

What a first install actually costs: ~3–5 GB of downloads/builds (whisper.cpp compile + multilingual Whisper model + Kokoro TTS with its PyTorch runtime), typically 15–45 minutes depending on your connection. The two voice services then stay resident (~1.5–2 GB RAM). If the final health check says a service isn't listening yet, it's usually still downloading — re-run scripts/setup.sh a few minutes later.

Recommended — let Claude Code install it

git clone https://github.com/michalstrnadel/flowcode-app.git
cd flowcode-app
claude            # then say:  "set up flowcode"

Claude Code reads AGENTS.md (and the bundled /setup skill) and installs everything end to end. Any agent that follows AGENTS.md works the same way.

Manual — run the script yourself

git clone https://github.com/michalstrnadel/flowcode-app.git
cd flowcode-app
scripts/setup.sh

Then launch flowcode.app — the orb appears in your menu bar. setup.sh checks prerequisites (Homebrew, uv, Swift), installs + starts Kokoro and Whisper as launchd agents, builds + signs the app, and opens the right System Settings panes. It's idempotent — safe to re-run.

Permissions (one time)

Feature	Microphone	Accessibility
Read-aloud (Claude Code)	—	—
Read-aloud (Claude Desktop)	—	✅ (to read its on-screen text)
Dictation (⌥)	✅	✅ (to paste the transcript)

Claude Code read-aloud works immediately with no permissions. Dictation and Claude Desktop read-aloud need Accessibility (the same single grant); dictation also needs the Microphone. flowcode prompts the first time you hold ⌥. (macOS can't grant these from a script — you flip the toggles in System Settings → Privacy & Security.)

Czech voice (optional)

Pick Language ▸ Čeština in the menu and flowcode offers to download a neural Czech voice (~350 MB, one-time, fully offline) — English users never download it. Prefer the CLI? Run scripts/setup.sh --czech or the /czech-voice skill. Czech dictation works with the multilingual Whisper model (small by default; setup.sh --model medium for higher accuracy).

The menu

◉  Speaking — reading Claude's reply
─────────
Pause Voice            ⌃⌥Space        ↔ Resume Voice
Stop Speaking                          (enabled while speaking)
─────────
  Read replies ▸  Full · Compact · Off  (how much to speak; live)
  Voice ▸  Sky · Bella · Adam · …       (pick a Kokoro voice — English)
  Language ▸  English · Čeština         (read-aloud + dictation; live)
  Listen to ▸  Claude Code · Claude Desktop · Both
  Hold Right Option (⌥) to dictate
─────────
✓ Read messages aloud                   (experimental switch; relaunch to apply)
✓ Launch at Login                       (real SMAppService login item)
  Open Log…
─────────
Quit flowcode          ⌘Q

How it works

Claude Code JSONL ─tail─┐
                        ├─▶ flowcode ─HTTP─▶ Kokoro :8880 (EN) / Coqui :8771 (CS) ─▶ 🔊 + orb
Claude Desktop  AX ─────┘
        ⌥ hold ──▶ mic capture ──HTTP──▶ Whisper STT (:2022) ──paste──▶ focused app

flowcode reads from one or both sources: it tails the transcript Claude Code already writes (~/.claude*/projects/…/<session>.jsonl, active session only), and/or observes the Claude desktop app's on-screen replies via the macOS Accessibility tree (it keeps conversations server-side, so there's no file to tail). Each new reply is spoken by Kokoro (English) or the on-demand Coqui voice (Czech). The mic opens only while you hold ⌥, and closes the instant you let go. No socket, no Python core, no MCP server — read-aloud and dictation are self-contained in the Swift app plus the local voice services.

Reading the Claude desktop app is best-effort. It scrapes the app's Accessibility tree, which a future Claude UI update could change. If it misbehaves, switch Listen to → Claude Code or Read replies → Off; the Claude Code path is unaffected.

Troubleshooting

• No audio → confirm the services: curl -fsS http://127.0.0.1:8880/v1/audio/voices and curl -fsS http://127.0.0.1:2022/health. Re-run scripts/setup.sh if needed; logs are in ~/.voicemode/logs/.
• Dictation silent → grant Accessibility + Microphone to flowcode, then relaunch. (Dev builds are ad-hoc signed, so a rebuild may require re-granting.)
• The orb is stuck → Pause/Resume (⌃⌥Space), or quit and relaunch.

Experimental / dormant

flowcode began as a real-time, interruptible voice core (barge-in, streaming TTS, semantic endpointing, a confirmation gate, and a swarm/orchestration HUD), built on a fork of voicemode. That code is still in the repo but off by default — it needs a running voicemode voice core and a control socket, which the shipping read-aloud experience never uses. It's preserved as the roadmap to true barge-in. See PLAN.md and BOUNDARIES.md (these predate the current default).

Building from source

swift build                 # flowcodeKit + the menu-bar app
swift run flowcode          # run from the build dir (dev, ad-hoc signed)
swift run flowcode-selftest # headless verification harness — must print ALL PASS
scripts/preflight.sh        # build + selftest + watchdog typecheck gate

See DISTRIBUTION.md for the notarized-release pipeline (Developer ID + Sparkle + Homebrew) and CLAUDE.md for contributor conventions.

Credits

Voice engines: Kokoro (TTS) and Whisper (STT). Built on a fork of voicemode (Mike Bailey). Full attribution in THIRD-PARTY-NOTICES.md.

License

MIT • Michal Strnadel (michalstrnadel)