# Yappy quickstart

From nothing to your first dictated sentence takes about two minutes, most of
which is macOS asking permission.

## 1. Download and install

Get the notarized disk image from [yappy.biz/download](https://yappy.biz/download),
open it, and drag **Yappy** to Applications. The direct URL for the current
release is also available programmatically:

```bash
curl -s https://yappy.biz/api/v1/releases/latest | jq -r .download_url
```

Yappy is signed with a Developer ID and notarized by Apple, so Gatekeeper opens
it without a right-click dance.

## 2. Launch it

Yappy lives in the menubar — look for the mic icon, not the Dock. There is no
main window; **Settings…** from the menubar opens a native window with tabs for
Dictation, Engine, Agent, and Files.

## 3. Grant Microphone

macOS prompts the first time you hold the dictation key. Allow it. Without the
microphone there is nothing to transcribe.

## 4. Grant Accessibility

**System Settings → Privacy & Security → Accessibility → enable Yappy.**

This is the permission that lets Yappy see the global hotkey and insert text into
whatever app you are using. macOS only re-reads the grant at launch, so **quit
and relaunch Yappy** after enabling it.

## 5. Say something

Put your cursor in any text field. **Hold Right ⌥ (Option)**, speak, release.
Clean, punctuated text appears where the cursor was.

Double-tap the key instead of holding it to lock recording on for hands-free
dictation; tap again to stop.

## 6. Optional — try Agent Mode

**Hold Right ⌘ (Command)** and ask for something: *"reply to Sarah and say I'll
be ten minutes late."* The agent reads the screen, acts in the app you are in,
and narrates each step in the notch. It stops before anything irreversible — a
send, a purchase, a login — and waits for you to confirm out loud.

Agent Mode runs through the `claude` CLI. If you do not have it:

```bash
curl -fsSL https://claude.ai/install.sh | bash   # per-user, no sudo
claude                                           # sign in, then /exit
```

## 7. Optional — go fully offline

```bash
brew install ollama && ollama pull qwen2.5:3b
```

Then set the cleanup provider to `ollama` in Settings → Engine. Dictation,
cleanup, and screen context now all run on your Mac with the network off.

## What next

- [Dictation](https://yappy.biz/docs/dictation) — personas, hands-free, spacing
- [LLM backends](https://yappy.biz/docs/backends) — pick the right cleanup model
- [Troubleshooting](https://yappy.biz/docs/troubleshooting) — if the hotkey does nothing

---

Canonical: https://yappy.biz/docs/quickstart/ · Last updated: 2026-08-25