parrot README

The project's README from github.com/humanitas-labs/parrot. As one markdown file: README.md.

parrot

parrot

Hold fn, speak, release. Your words appear at the cursor. On-device dictation for macOS.

1. Install

Download Parrot.dmg, drag Parrot to Applications, and open it. Turn on Parrot when macOS asks for Accessibility and the microphone. The first start downloads the speech model (about 150 MB).

Or from a terminal, which also installs the parrot command:

curl -fsSL https://perroquet.xyz/install.sh | sh

Requires macOS 14+ on Apple Silicon. Parrot is signed and notarized, so permissions survive updates, and it updates itself: it checks once a day, and Check for Updates… in its menu checks now. Upgrading from the command-line version: open the new app once and it replaces the old install.

2. Usage

  1. Click into any text field.
  2. Hold fn and speak. A small pill at the bottom of the screen shows the mic is live.
  3. Release. The transcript is pasted at the cursor, usually within 200–300 ms, and your clipboard is restored.

Choose Launch at login in the menu to start Parrot with your Mac. If fn is mapped to input source or emoji, parrot doctor shows how to fix it.

3. Dictionary

Add your names and technical terms to ~/.config/parrot/dictionary.json, and Parrot spells them your way. Edits apply on the next dictation. See docs/dictionary.md.

4. CLI

Command What it does
parrot Run in the foreground (^C to quit)
parrot setup One-time setup: permissions and model download
parrot doctor Check permissions and the fn key setting
parrot install --launch-at-login Start Parrot at login
parrot install --cli Link /usr/local/bin/parrot to Parrot.app
parrot install --uninstall Stop launching at login and remove logs
parrot models list List available models
parrot --model whisper-large-v3-turbo Larger, multilingual model
parrot --no-overlay Hide the recording pill
parrot --inject-mode type-unicode Type instead of paste (leaves the clipboard alone)

5. How it works

WhisperKit runs Whisper on the Apple Neural Engine via CoreML, AVAudioEngine captures the mic, a CGEventTap watches the hotkey, and a synthesized ⌘V pastes the result. Nothing leaves your Mac, and logs never contain what you said. See docs/architecture.md.

6. Build from source

swift build -c release && swift test
scripts/dev-install.sh      # build, sign, install Parrot.app, link the CLI

7. License

MIT

parrot (humanitas-labs/parrot)

Searching Database…

1.3K ·GitHub
What is this?Parrot is on-device dictation for macOS: hold the fn key, speak, release, and your words appear at the cursor as text.
Is this a regular Mac app or a terminal tool?Both: it ships as a Parrot.app you install from a dmg, and installing from the terminal also links a parrot command for setup, models and options.
Do I need to install anything else before it works?No, nothing: Parrot only needs those two macOS permissions and downloads its own speech model on first start.
What if my fn key is already mapped to something else?If fn switches the input source or opens the emoji picker, run parrot doctor — it checks your permissions and fn setting and shows how to fix the conflict.
Will it run on my Mac?Only on Apple Silicon Macs running macOS 14 or newer; Intel machines and older macOS versions are not supported.
Does anything I say leave my Mac?No. WhisperKit runs Whisper on the Apple Neural Engine via CoreML, so recognition happens entirely on-device, and the logs never contain what you said.
Can I teach it my names and technical terms?Yes. Add them to ~/.config/parrot/dictionary.json and Parrot spells them your way; edits apply from the next dictation.
Can I swap in a bigger or multilingual model?Yes. parrot models list shows what is available, and parrot --model whisper-large-v3-turbo runs the larger multilingual model.
Does it keep itself up to date?Yes. Parrot is signed and notarized, so permissions survive updates, and it checks for new versions once a day; Check for Updates in its menu checks right away.
What can I tweak from the command line?Hide the recording pill with --no-overlay, or use --inject-mode type-unicode to type instead of paste so the clipboard is left alone; parrot install --launch-at-login starts Parrot with your Mac.
Size
1.4 MB
Stars
1.3K
Age
5mo
Commits · 90 Days