muninn

AI-native macOS menu-bar dictation for developer text.

Muninn records speech, transcribes it, runs the transcript through a configurable text pipeline, and injects the final text into the active app. The default pipeline is designed for code-adjacent dictation: commands, flags, package names, file paths, environment variables, acronyms, and other tokens that general-purpose dictation often changes.

Contents

• What Muninn does
• Quick start
• Install and run
• Configure Muninn
• Transcription providers
• Pipeline model
• Streaming transcription
• Contextual profiles and voices
• External control
• Privacy, replay, and debugging
• Development
• Current limits
• Source map

What Muninn does

Default recorded-mode flow:

hotkey or tray click
-> record temporary WAV
-> resolve transcription provider route
-> transcribe with the first usable provider
-> run the refine step
-> run optional external filters
-> inject final text into the active app

Muninn includes:

• a macOS menu-bar app with a live tray indicator
• global hotkeys for push-to-talk, done-mode toggle, and cancel
• microphone capture to a temporary WAV, defaulting to 16 kHz mono
• a local-first transcription route across Apple Speech, whisper.cpp, Deepgram, OpenAI, and Google recorded transcription
• an optional streaming mode for providers that support live transcription in this codebase
• a built-in refine step that applies a conservative developer-dictation prompt
• external Unix filter support for custom pipeline steps
• keyboard-event text injection into the current app
• optional external control through muninn:// URLs and a localhost MCP server
• optional replay artifacts for debugging utterances

Default controls:

Hotkey changes are parsed from config, but live config reload does not replace active hotkey bindings. Restart Muninn after changing hotkeys.

Configure Muninn

The canonical sample is configs/config.sample.toml. The root schema lives in src/config.rs.

Important config sections

Provider route

The default provider route is local-first:

[transcription]
providers = ["apple_speech", "whisper_cpp", "deepgram", "openai", "google"]

Profiles can override only the route:

[profiles.mail.transcription]
providers = ["deepgram", "openai", "google"]

If you still have explicit stt_* steps in pipeline.steps, Muninn accepts them and infers the route from that order. New configs should prefer [transcription].providers.

Pipeline steps

Each pipeline step has:

• id
• cmd
• optional args
• optional io_mode
• timeout_ms
• on_error

Supported io_mode values:

Supported on_error values:

Example:

[transcription]
providers = ["apple_speech", "whisper_cpp", "deepgram", "openai", "google"]

[[pipeline.steps]]
id = "refine"
cmd = "refine"
timeout_ms = 2500
on_error = "continue"

[[pipeline.steps]]
id = "uppercase"
cmd = "/usr/bin/tr"
args = ["[:lower:]", "[:upper:]"]
timeout_ms = 250
on_error = "continue"

Refine prompt hints

transcript.system_prompt and transcript.system_prompt_append steer the built-in refine step. They do not change the speech-to-text provider, and Muninn does not parse appended JSON into provider-native adaptation APIs.

[transcript]
system_prompt = "Prefer minimal corrections. Focus on technical terms, developer tools, package names, commands, flags, file names, paths, env vars, acronyms, and obvious dictation errors. If uncertain, keep the original wording."
system_prompt_append = """
Vocabulary JSON:
{"terms":["Muninn","whisper.cpp","Deepgram","Cargo.toml"],"commands":["cargo test --all-targets","rg --files"],"paths":["src/config.rs",".env"]}
"""

Transcription providers

The refine step is not an STT provider. It uses the [refine] config and OpenAI-compatible chat completions by default.

Environment variables

Stub variables are intended for local smoke checks and tests. They bypass live provider calls for the matching step.

whisper.cpp model lifecycle

Default behavior:

• providers.whisper_cpp.model unset resolves to tiny.en
• tiny.en resolves to ggml-tiny.en.bin
• default model directory is ~/.local/share/muninn/models
• Muninn auto-downloads known canonical models on first use
• explicit custom model paths must already exist
• device = "auto" uses Metal on supported Apple Silicon builds and CPU otherwise

Pre-warm the default model cache:

mkdir -p "$HOME/.local/share/muninn/models"
curl -L \
  -o "$HOME/.local/share/muninn/models/ggml-tiny.en.bin" \
  "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin"

If a local-only route points at a missing custom model, Muninn records a missing_whisper_cpp_model diagnostic and injects nothing unless another provider later produces transcript.raw_text.

Pipeline model

Muninn passes an envelope through every built-in and external step. Built-in STT steps fill transcript.raw_text; transform steps such as refine write output.final_text. Injection prefers output.final_text and can fall back to transcript.raw_text.

Built-in step commands:

Run a built-in step directly for smoke checks:

cargo run -q -- __internal_step <stt_apple_speech|stt_whisper_cpp|stt_deepgram|stt_openai|stt_google|refine>

Use the JSON fixtures in tests/fixtures for example input envelopes.

Streaming transcription

Recorded mode is the default. Enable streaming explicitly:

[transcription]
mode = "streaming"
providers = ["deepgram", "openai"]

[transcription.streaming]
frame_ms = 100
finish_timeout_ms = 10000
fallback_to_recorded_on_error = true

Streaming behavior:

• Deepgram streaming sends mono LINEAR16 audio over WebSocket.
• OpenAI streaming uses Realtime transcription and forces 24 kHz mono capture for that utterance.
• Google streaming is not currently callable because the pinned google-cloud-speech-v2 1.12.0 dependency exposes request and response types but no callable streaming method.
• Muninn still writes the completed WAV during streaming.
• When streaming fails and fallback_to_recorded_on_error = true, Muninn can run the completed-WAV route.
• A successful streaming transcript seeds transcript.raw_text; refine, scoring, replay, and injection use the same downstream pipeline as recorded mode.
• Interim streaming results are transient. Muninn does not show a partial transcript UI or persist partial transcript history.

Contextual profiles and voices

Muninn can change refine behavior based on the frontmost app. It captures the bundle id, app name, and a best-effort window title, then applies the first matching profile_rules entry. If no rule matches, behavior falls back to [app].profile; the idle tray glyph falls back to M.

Resolution order:

1. Start from the base config.
2. Apply the matched voice, if the matched profile names one.
3. Apply profile overrides last.

Voice means text-shaping behavior plus an optional tray glyph, not an audio voice.

[app]
profile = "default"

[voices.codex]
indicator_glyph = "C"
system_prompt = "Prefer terse developer dictation. Keep commands, flags, file names, and code tokens intact."
system_prompt_append = """
Vocabulary JSON:
{"terms":["Codex","Muninn","Cargo.toml"],"commands":["cargo test --all-targets","cargo clippy --all-targets -- -D warnings"]}
"""

[voices.terminal]
indicator_glyph = "T"
system_prompt = "Preserve shell commands exactly. Prefer minimal punctuation changes."

[profiles.codex]
voice = "codex"

[profiles.terminal]
voice = "terminal"

[[profile_rules]]
id = "codex-app"
profile = "codex"
app_name = "Codex"

[[profile_rules]]
id = "terminal-app"
profile = "terminal"
bundle_id = "com.apple.Terminal"

Tray behavior:

• idle preview shows the glyph for the matched voice, or M
• recording and processing freeze the resolved glyph for that utterance
• ? is reserved for missing-credentials feedback

External control

Muninn can be driven by agents and scripts through two transports:

• muninn:// URL scheme, available for the packaged macOS .app
• localhost streamable-HTTP MCP server, disabled by default

Both transports use the same recording-control vocabulary as tray and hotkey events.

[external_control]
url_scheme_enabled = true
mcp_enabled = false
start_recording_enabled = false
mcp_bind_address = "127.0.0.1:2769"

Action semantics:

External start is disabled by default because it starts microphone capture. Enabling start_recording_enabled = true is the local trust decision for configured agents and scripts.

URL scheme

The packaged .app registers muninn:// through CFBundleURLTypes.

open "muninn://record"

A binary launched with cargo run does not receive these LaunchServices links.

MCP server

When mcp_enabled = true, Muninn serves MCP at:

http://127.0.0.1:2769/mcp

Tools:

• get_status
• start_recording
• stop_recording
• cancel_recording

Example registration with an MCP-aware client:

auggie mcp add muninn --transport http --url http://127.0.0.1:2769/mcp

get_status is read-only and returns JSON like:

{
  "state": "idle",
  "recording_active": false,
  "busy": false,
  "permissions": {
    "microphone": "granted",
    "accessibility": "granted",
    "input_monitoring": "granted"
  }
}

state is one of idle, recording_active, permission_blocked, already_running, or failed.

Security constraints:

• The MCP server has no authentication.
• mcp_bind_address must be an explicit loopback socket address such as 127.0.0.1:2769 or [::1]:2769.
• Muninn refuses wildcard, LAN, hostname, and other non-loopback binds.
• The MCP server starts only at app launch. Changing mcp_enabled later requires restarting Muninn.

Privacy, replay, and debugging

Tracing logs go to stderr and are controlled with RUST_LOG.

RUST_LOG=recording=debug cargo run --release --bin muninn

Replay logging is disabled by default. When enabled:

• replay_detail = "minimal" stores sparse utterance metadata only
• replay_detail = "full_debug" stores redacted config, target context, final envelopes, pipeline outcome, refine context, and injection route
• replay_retain_audio = true keeps audio only when replay_detail = "full_debug"
• retained audio uses a hard link when possible and falls back to a copy
• full-debug snapshots redact provider secrets and prompt fields
• replay artifacts are for inspection, not re-run

[logging]
replay_enabled = true
replay_detail = "minimal"
replay_retain_audio = false
replay_dir = "~/.local/state/muninn/replay"
replay_retention_days = 7
replay_max_bytes = 52428800

Common recovery checks:

Development

Run the core checks:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets

The repository also includes prek hooks:

prek validate-config
prek run --all-files
prek install

Run the benchmark suite:

cargo bench --bench runtime_bottlenecks

Filter to one benchmark group:

cargo bench --bench runtime_bottlenecks pipeline_runner
cargo bench --bench runtime_bottlenecks replay_persist

The benchmark target focuses on per-utterance latency paths that do not require network calls:

• audio output transform and resampling
• envelope JSON round trips
• Google request-body construction
• profile and voice resolution
• replacement scoring
• in-process pipeline runner overhead
• replay persistence with and without retained audio artifacts

Current limits

• Muninn's supported runtime is macOS.
• Apple Speech requires macOS 26+ and Apple-managed Speech assets.
• whisper.cpp and Apple Speech are completed-recording providers only.
• Google streaming request construction exists, but live Google streaming is not callable until the pinned official client exposes a streaming RPC.
• Streaming mode uses provider final text only. There is no partial transcript UI.
• Replay artifacts are for inspection, not deterministic replay.
• Provider-backed transcription needs realistic timeout budgets.
• The external-control MCP server has no authentication, is disabled by default, binds loopback-only, and starts only at app launch.
• The repository release workflow packages raw binaries; use the local packaging script when you need a .app bundle.

Source map

Use these files when checking README claims against source:

Quick start

Use this path when you want to run Muninn from this repository.

Prerequisites

• macOS
• Rust 1.88.0 or newer
• Xcode command line tools for local builds
• macOS permissions for Microphone, Accessibility, and Input Monitoring
• Optional cloud provider keys when you use Deepgram, OpenAI, Google, or the default OpenAI-backed refine step

1. Build the binary

cargo build --release --bin muninn

2. Create a config file

Muninn reads config in this order:

1. MUNINN_CONFIG
2. $XDG_CONFIG_HOME/muninn/config.toml
3. ~/.config/muninn/config.toml

If the resolved config file is missing, Muninn creates a launchable default config. To start from the sample config instead:

CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/muninn"
mkdir -p "$CONFIG_DIR"
cp configs/config.sample.toml "$CONFIG_DIR/config.toml"

3. Set credentials when needed

Muninn loads ./.env from the current working directory by default. Existing shell environment variables override .env and config values.

Create .env only with the keys you use:

OPENAI_API_KEY=<OPENAI_API_KEY>
DEEPGRAM_API_KEY=<DEEPGRAM_API_KEY>
GOOGLE_API_KEY=<GOOGLE_API_KEY>
GOOGLE_STT_TOKEN=<GOOGLE_STT_TOKEN>

Set MUNINN_LOAD_DOTENV=0, false, or no to disable .env loading.

4. Run the tray app

cargo run --release --bin muninn

Expected result: Muninn appears in the macOS menu bar with an M tray indicator.

5. Grant permissions and verify

Grant these permissions to Muninn itself:

To verify the app:

1. Focus a text field in another app.
2. Click the Muninn tray icon to start recording.
3. Speak a short phrase.
4. Click the tray icon again to stop recording.

Expected result: Muninn transcribes the utterance, runs the pipeline, and types the final text into the focused app.

If macOS stops showing a permission prompt, reset the affected TCC service and relaunch Muninn:

tccutil reset ListenEvent
tccutil reset Accessibility
tccutil reset Microphone

Install and run

Install from crates.io

cargo install muninn-speech-to-text
muninn

The package name is muninn-speech-to-text; the binary name is muninn.

Run from the sample config

MUNINN_CONFIG="$PWD/configs/config.sample.toml" cargo run --release --bin muninn

This is useful for local development because it avoids changing your user config.

Install a release binary

The release workflow builds tar archives for:

• aarch64-apple-darwin
• x86_64-apple-darwin

After extracting a release archive, keep the binary at a stable path before granting macOS permissions:

mkdir -p "$HOME/.local/bin"
mv muninn "$HOME/.local/bin/muninn"
chmod +x "$HOME/.local/bin/muninn"
"$HOME/.local/bin/muninn"

macOS permissions attach to the exact app or binary identity. Moving or replacing a raw binary can require granting permissions again.

Build a local .app bundle

Use the app bundle when you want a stable app identity, muninn:// URL handling, and normal Login Items behavior.

cargo build --release --bin muninn
bash scripts/package-macos-app.sh
open dist/Muninn.app

The packaging script creates dist/Muninn.app, signs it ad hoc by default, and creates dist/Muninn.app.zip when ditto is available. Set CODESIGN_IDENTITY to use a Developer ID certificate, or set CODESIGN_APP=0 to skip signing.

Recommended app-bundle setup:

1. Move dist/Muninn.app to /Applications/Muninn.app.
2. Launch it once and grant permissions to Muninn.
3. Add it under System Settings > General > Login Items.
4. Keep [app].autostart = false when using Login Items.

Finder and Login Items do not inherit your shell environment. Store credentials in config or make sure Muninn's working directory contains the .env file you expect it to read.

Enable raw-binary autostart

Set [app].autostart = true to let Muninn write a LaunchAgent for the current executable path.

Behavior:

• Muninn writes ~/Library/LaunchAgents/com.bnomei.muninn.plist when it starts or reloads config.
• Changes take effect on the next macOS login.
• The LaunchAgent includes MUNINN_CONFIG.
• The LaunchAgent does not inherit interactive shell exports.
• When using Muninn.app, prefer macOS Login Items over this raw-binary LaunchAgent path.