Docs — ptarmigan-flow

Quick start

Up and running in four commands

Install via Homebrew, verify your environment, grant macOS permissions, then start the daemon. The pflow alias works everywhere ptarmigan-flow does.

brew tap nakak10/ptarmigan-flow https://github.com/NAKAK10/ptarmigan-flow
brew install ptarmigan-flow
pflow doctor
pflow check-permissions --request
pflow run

Prefer a GUI? Download the signed Mac app instead — it walks you through permissions in a setup window.

Commands

Full command reference

pflow is a short alias for ptarmigan-flow. Append --help to any command for the full flag list.

Core

Command	What it does
pflow run	Start the push-to-talk daemon in the foreground.
pflow doctor	Run runtime diagnostics — checks permissions, STT backend, and launchd status.
pflow init	Interactive config editor; shows current values as defaults.
pflow config <section>	Edit one config section (`audio`, `stt`, `output`, `hotkey`, …).
pflow config language	Pick transcription language from a described menu (`en`, `ja`, `zh`, custom).
pflow update	Run `brew upgrade ptarmigan-flow` and refresh the launch agent if installed.

Launch agent (auto-start at login)

Command	What it does
pflow install-launch-agent	Install launchd agent for auto-start at login. Also requests any missing permissions.
pflow restart-launch-agent	Restart the agent — required after granting new macOS permissions.
pflow uninstall-launch-agent	Remove the launchd agent.
pflow doctor --launchd-check	Detailed diagnostics including launchd permission binding status.

Listing & selection

Command	What it does
pflow list model	Browse and select from verified STT model presets. Saves choice to config.
pflow list model --hub-search <query> --backend <b> --limit 20	Search public Hugging Face Hub ASR models and install any result.
pflow list devices	List available audio input devices and save selection to config.
pflow list ollama	List downloaded Ollama models and select one for LLM post-correction.
pflow list lmstudio	List loaded LM Studio models and select one for LLM post-correction.

Permissions

Command	What it does
pflow check-permissions	Check current macOS permission status (Microphone, Accessibility, Input Monitoring).
pflow check-permissions --request	Check and request any missing permissions via system dialogs.

Models

STT model reference

All models run locally. Switch with pflow list model. The token goes in ~/.config/ptarmigan-flow/config.toml as stt.model.

Token	Label	Notes
moonshine:tiny	Moonshine tiny	Fastest. Bundled in the Mac app. English-focused. Minimal RAM.
moonshine:base	Moonshine base	Slightly larger than tiny. Better accuracy with still fast response. English-focused.
granite:ibm-granite/granite-4.0-1b-speech	IBM Granite 4.0 1B Speech	Recommended default. Good Japanese & English accuracy. Uses MLX on Apple Silicon, Transformers on other platforms.
mlx:openai/whisper-large-v3-turbo	Whisper large-v3-turbo	OpenAI's battle-tested model via MLX. Strong multilingual accuracy across 99 languages. Apple Silicon only.
voxtral:mistralai/Voxtral-Mini-4B-Realtime-2602	Mistral Voxtral Mini 4B	Real-time capable multilingual model. Runs via MLX Audio on Apple Silicon.
vllm:<any-model-id>	vLLM (custom server)	Point to your own vLLM endpoint. `--max-model-len` is derived from `audio.max_record_seconds` automatically.

Hugging Face Hub search

Any public ASR model on the Hub can be used. Hub results are marked unverified but accept the same backend:repo_id format:

pflow list model --hub-search whisper --backend mlx --limit 20

Set HF_TOKEN in your environment to raise rate limits or access private models.

AI Correction

Post-process with a local LLM

After each STT transcription, ptarmigan-flow can pass the text through a local language model for context-aware corrections: proper nouns, punctuation, domain jargon. All of this runs locally — nothing leaves your Mac.

Enable via Ollama

Make sure Ollama is running, then:

pflow list ollama          # pick a model
pflow config text          # set mode = "always"

Enable via LM Studio

pflow list lmstudio        # pick a loaded model
pflow config text          # set provider = "lmstudio", mode = "always"

Relevant config keys

Key	Values / default
text.llm_correction.mode	`never` (default) · `always` · `ask`
text.llm_correction.provider	`ollama` · `lmstudio`
text.llm_correction.base_url	Ollama default: `http://localhost:11434`
text.llm_correction.model	e.g. `qwen2.5:7b-instruct`
text.llm_correction.timeout_seconds	Clamped `0.5–5.0`, default `5.0`
text.llm_correction.max_input_chars	Clamped `50–5000`, default `500`

Configuration

Config file reference

Config lives at ~/.config/ptarmigan-flow/config.toml. Missing on first run — it is auto-created. Edit interactively with pflow init or open the file directly.

Hotkey

Key	Default / notes
hotkey.key	`right_cmd` — right ⌘ key. Change to any key name pynput recognises.

Audio

Key	Default / notes
audio.input_device	Unset = system default. Set to device name or index from `pflow list devices`.
audio.input_device_policy	`playback_friendly` (avoids Bluetooth HFP mic) · `system_default` · `external_preferred`
audio.max_record_seconds	`30` — max single recording length in seconds.
audio.trailing_silence_seconds	`1.0` (clamped 0–1) — silence appended for decoder stability.

STT model

Key	Default / notes
stt.model	`moonshine:tiny` — see the Models section for all tokens.
stt.idle_shutdown_seconds	`30.0` — release backend resources after this many idle seconds. `0` disables.
stt.vllm.startup_preset	`off` · `balanced` · `fastest` — only applies to `vllm:` models.

Output

Key	Default / notes
output.mode	`direct_typing` (clipboard untouched) · `clipboard_paste`
language	`en` · `ja` · `zh` · any custom code. Use `pflow config language` for a picker.

Runtime UI

Key	Default / notes
runtime.ui_enabled	`true` — toggle all runtime overlays.
runtime.activity_indicator_enabled	`true` — show the corner recording/transcription indicator.
runtime.activity_indicator_margin_right	`24` px from right edge.
runtime.activity_indicator_margin_bottom	`24` px from bottom edge.
runtime.activity_indicator_size	`42` px (minimum 16).

Troubleshooting

Common issues

Permissions show "ON" but the app still reports them missing

This only affects locally built / ad-hoc signed binaries. macOS ties Accessibility and Input Monitoring to the binary's CDHash, which changes on every rebuild. Reset and re-grant:

tccutil reset Accessibility com.ptarmiganflow.app
tccutil reset ListenEvent com.ptarmiganflow.app

Homebrew install fails with "Broken Python installation"

brew reinstall python@3.11
brew untap nakak10/ptarmigan-flow
brew tap nakak10/ptarmigan-flow https://github.com/NAKAK10/ptarmigan-flow
brew update
brew reinstall ptarmigan-flow

After granting permissions, the daemon still does not detect them

Permissions are bound to the executable, not just the process. Restart the launch agent to rebind:

pflow restart-launch-agent
pflow doctor --launchd-check

Audio quality drops during Bluetooth playback

Set audio.input_device_policy = "playback_friendly" in config (this is the default). Leave audio.input_device unset so ptarmigan-flow can choose a non-HFP mic automatically.

For detailed edge cases and all config options, see README.llm.md in the repository.

Command & ConfigReference