koe

Koe (声)

A background-first macOS voice input tool. Press a hotkey, speak, and the corrected text is pasted into whatever app you're using.

For more information, visit the documentation at koe.li.

The Name

Koe (声, pronounced "ko-eh") is the Japanese word for voice. Written as こえ in hiragana, it's one of the most fundamental words in the language — simple, clear, and direct. That's exactly the philosophy behind this tool: your voice goes in, clean text comes out, with nothing in between. No flashy UI, no unnecessary steps. Just 声 — voice, in its purest form.

Why Koe?

I tried nearly every voice input app on the market. They were either paid, ugly, or inconvenient — bloated UIs, clunky dictionary management, and too many clicks to do simple things.

Koe takes a different approach:

• Minimal runtime UI. Koe stays out of the way with a menu bar item, a small floating status pill with native frosted-glass vibrancy during active sessions, optional post-processing template actions above the result bubble, and an optional built-in settings window when you actually need to configure it.
• All configuration lives in plain text files under ~/.koe/. You can edit them with any text editor, vim, a script, or the built-in settings UI.
• Dictionary is a plain .txt file. No need to open an app and add words one by one through a GUI. Just edit ~/.koe/dictionary.txt — one term per line. You can even use Claude Code or other AI tools to bulk-generate domain-specific terms.
• Changes take effect immediately. Edit any config file and the new settings are used automatically. ASR, LLM, dictionary, and prompt changes apply on the next hotkey press. Hotkey changes are detected within a few seconds. No restart, no reload button.
• Tiny footprint. Even after installation, Koe stays under 15 MB, and its memory usage is typically around 20 MB. It launches fast, wastes almost no disk space, and stays out of your way.
• Built with native macOS technologies. Objective-C handles hotkeys, audio capture, clipboard access, permissions, and paste automation directly through Apple's own APIs.
• Rust does the heavy lifting. The performance-critical core runs in Rust, which gives Koe low overhead, fast execution, and strong memory safety guarantees.
• No Chromium tax. Many comparable Electron-based apps ship at 200+ MB and carry the overhead of an embedded Chromium runtime. Koe avoids that entire stack, which helps keep memory usage low and the app feeling lightweight.

How It Works

1. Press the trigger shortcut (default: Fn, configurable). Use hold to press-and-hold, toggle to tap once to start/stop, or double_tap to double-tap to start and single-tap to stop.
2. Audio streams in real-time to a cloud ASR service (Doubao/豆包 by ByteDance)
3. A floating status pill shows real-time interim recognition text as you speak
4. The overlay stays visible through ASR finalization and LLM correction, so you can see both the final transcript and corrected result
5. The corrected text is automatically pasted into the active input field
6. If overlay templates are enabled, you can optionally click a template or press 1-9 to rewrite the result and copy that variant to the clipboard

ASR provider support:

• Cloud: Doubao (豆包) and Qwen (通义) streaming ASR
• Local: Apple Speech (macOS 26+, zero-config on-device), MLX (Apple Silicon, Qwen3-ASR models), and sherpa-onnx (CPU, streaming zipformer models)
• LLM: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, compatible gateways, or MLX local models
• Planned: future ASR support may include the OpenAI Transcriptions API

Installation

Koe is Apple Silicon only. Two prebuilt apps are published per release: Koe (the standard app; cloud + Apple Speech providers) and Koe MLX (adds on-device MLX model support). Both are signed, notarized, and update themselves via Sparkle.

Homebrew

brew install koe --cask

Release

You can also download the latest release directly from GitHub:

• Download the latest release

App Updates

Koe updates itself in-app via Sparkle. Each build variant checks its own appcast feed hosted in this repository:

• Koe (standard): https://raw.githubusercontent.com/missuo/koe/main/docs/appcast.xml
• Koe MLX: https://raw.githubusercontent.com/missuo/koe/main/docs/appcast-mlx.xml

Updates are checked automatically every 6 hours (and on demand from the menu bar with Check for Updates...). When a new version is available, Sparkle downloads the signed, notarized zip, verifies its EdDSA signature against the public key embedded in the app, and installs it in place — no browser round-trip.

The appcasts (and the legacy docs/update-feed.json used by pre-Sparkle builds) are updated automatically by the release workflow on every tagged release; they are not edited by hand. See docs/release-signing.md for the full release pipeline.

Build from Source

Prerequisites

• macOS 14.0+
• Apple Silicon Mac
• Rust toolchain (rustup)
• Xcode with command line tools
• xcodegen (brew install xcodegen)

Build

git clone https://github.com/missuo/koe.git
cd koe

# Generate Xcode project
cd KoeApp && xcodegen && cd ..

# Build the standard app (cloud + Apple Speech)
make build

# Build the MLX app (adds on-device MLX models)
make build-mlx

Run

make run

Or open the built app directly:

open ~/Library/Developer/Xcode/DerivedData/Koe-*/Build/Products/Release/Koe.app

Permissions

Koe requires three core macOS permissions to function, plus one provider-specific permission when you use Apple Speech. You'll be prompted to grant them on first launch. Without any of the three core permissions, Koe cannot complete its main workflow.

To grant permissions: System Settings → Privacy & Security → enable Koe under the relevant categories above.

Koe may also ask for Notifications permission. This is optional and is only used for warning/error notifications and update-related diagnostics.

Configuration

All config files live in ~/.koe/ and are auto-generated on first launch. You can edit them directly, or use the built-in settings window (Setup Wizard) from the menu bar. The settings window includes tabs for ASR, LLM, Controls, Dictionary, System Prompt, Templates, and About. The System Prompt tab edits system_prompt.txt; the Templates tab manages prompt-template visibility, ordering, and prompts; advanced knobs such as user_prompt.txt, ASR custom headers, and advanced profile fields such as no_reasoning_control remain file-based settings. When a local ASR provider is selected, the ASR tab shows provider-specific controls: model picker with download/delete for MLX and Sherpa-ONNX, or language picker with asset status and download for Apple Speech. The LLM tab supports multiple profiles for OpenAI-compatible APIs, APFEL, and local MLX models. Selecting MLX shows a model picker with download/status controls instead of API fields.

~/.koe/
├── config.yaml          # Main configuration
├── dictionary.txt       # User dictionary (hotwords + LLM correction)
├── history.db           # Usage statistics (SQLite, auto-created)
├── system_prompt.txt    # LLM system prompt (customizable)
├── user_prompt.txt      # LLM user prompt template (customizable)
└── models/              # Local ASR models
    ├── mlx/
    │   └── Qwen3-ASR-0.6B-4bit/
    │       ├── .koe-manifest.json
    │       └── *.safetensors, config.json, ...
    └── sherpa-onnx/
        └── bilingual-zh-en/
            ├── .koe-manifest.json
            └── *.onnx, tokens.txt, ...

config.yaml

Below is the full configuration with explanations for every field.

ASR (Speech Recognition)

Koe uses a provider-based ASR config layout. Built-in providers: Doubao, Qwen, Apple Speech (local, macOS 26+), MLX (local, Apple Silicon), and sherpa-onnx (local, CPU).