# Yappy configuration

Yappy reads `~/.yappy/config.json`, created on first run with `0600`
permissions. Everything in it is also reachable from **Settings…** in the
menubar; the file is there for people who would rather edit text.

## A representative config

```json
{
  "llm": { "provider": "hosted", "model": "" },
  "claudeBin": "/opt/homebrew/bin/claude",
  "pushToTalk": "rightOption",
  "language": "en",
  "handsFreeEnabled": true,
  "enableScreenContext": true,
  "injectionStyle": "paste",
  "typingWordDelayMs": 45,
  "autoUpdate": true,
  "shareUsageAnalytics": true,
  "agent": { "enabled": true, "key": "rightCommand", "model": "sonnet" }
}
```

## Keys

| Key | Type | Default | What it does |
|---|---|---|---|
| `llm.provider` | string | `hosted` | Which model cleans up the transcript. See [backends](https://yappy.biz/docs/backends). |
| `llm.model` | string | `""` | Empty means the provider's default model. |
| `claudeBin` | string | `/opt/homebrew/bin/claude` | Path to the `claude` CLI. Auto-corrected at launch if it lives elsewhere. |
| `pushToTalk` | string | `rightOption` | Dictation key. Modifier names, or `mouse3`, `mouse4`, and friends. |
| `language` | string | `en` | Dictation language. `"auto"` detects per utterance; pinning is more accurate. |
| `handsFreeEnabled` | bool | `true` | Double-tap the key to lock recording on. |
| `enableScreenContext` | bool | `true` | On-device OCR of the frontmost window for disambiguation. |
| `injectionStyle` | string | `paste` | `"type"` reveals the finished text one word at a time. Cosmetic and slower. |
| `typingWordDelayMs` | number | `45` | Per-word pause when `injectionStyle` is `"type"`. |
| `whisperModel` | string | bundled | Absolute path to a `ggml-*.bin` model to use instead of the default. |
| `autoUpdate` | bool | `true` | Check the signed appcast and update in place. Team-ID verified. |
| `shareUsageAnalytics` | bool | `true` | Anonymous product analytics. Never transcripts, audio, or screen contents. |
| `agent.enabled` | bool | `true` | Whether the Right ⌘ key starts an agent session at all. |
| `agent.key` | string | `rightCommand` | The Agent Mode key. |
| `agent.model` | string | `sonnet` | Family alias; resolves to the newest model in that family. |

## Upgrading the transcription model

```bash
WHISPER_MODEL=large-v3-turbo ./scripts/setup.sh
```

then:

```json
{ "whisperModel": "~/.yappy/models/ggml-large-v3-turbo.bin" }
```

`large-v3-turbo` is a clear accuracy win on Apple Silicon and still fast enough
to feel instant.

## After editing

Yappy picks up most changes on save. Hotkey changes (`pushToTalk`, `agent.key`)
and `whisperModel` take effect on relaunch, because the key tap and the model are
both established at startup.

## If the file is malformed

A JSON syntax error makes Yappy fall back to defaults rather than refusing to
start, and it says so in the menubar. Fix the file and relaunch.

---

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