Settings reference

Where your data lives

Picky is local-first and keeps everything under one durable folder:

~/Library/Application Support/Picky/
  Settings/settings.json    — every preference, including API keys (plain JSON)
  Workspace/                — main agent cwd, seeded AGENTS.md, optional .pi/*
  sessions/                 — Pickle session history (active + archived)
  picky.json                — main agent runtime state (compaction summaries, etc.)
  skills/                   — Picky-only skill catalog (<name>/SKILL.md, seeded once,
                              freely hand-authored or deleted afterwards)
  GeneratedReports/         — Markdown copies of reports (swept after 30 days)
  Logs/                     — picky-agentd stdout/stderr logs

Only screenshots are written outside this tree, to the per-user temporary directory (FileManager.default.temporaryDirectory/Picky/Screenshots), so capture bytes do not accumulate in the durable folder.

API keys typed into Settings are stored in plain JSON inside settings.json (OpenAI/Azure/ElevenLabs keys, custom base URLs). When Picky needs a credential, it resolves it in this order: (1) the matching settings.json field if non-empty, (2) the corresponding environment variable, (3) a consolidated Keychain entry at service com.jonghakseo.picky.azure-openai (account AZURE_OPENAI_VOICE_CONFIG) — so env and Keychain are fallbacks, not overrides. If you want to keep secrets out of plain JSON, clear the Settings field first, then populate the env var or Keychain entry. Picky never writes to the Keychain itself; you populate the Azure entry by hand (for example with security add-generic-password). If you back up or share settings.json, scrub the secret fields first. The Groq API key is the exception: Settings saves it in the macOS Keychain (service com.jonghakseo.picky.secrets, account GROQ_STT_API_KEY), never in settings.json.

Reinstalling Picky.app keeps everything above. macOS only replaces the bundle in /Applications; the Application Support tree and any Keychain entries you populated survive. The Alpha build’s “reinstall the latest alpha package” notice does not touch your settings, sessions, or workspace.

---

Hub Settings is one scrollable page with jump links for seven groups. The category links stay pinned at the top as you scroll, so you can switch groups without returning to the page title. The group headings explain their scope; Main Agent uses focused cards that pair a live summary with supporting details, so workspace/runtime paths do not compete with model, screen-capture, or delivery decisions.

Group	Contents
General	App language, appearance, Hub/report/terminal font scales, and update controls.
Accounts and agents	Pi OAuth accounts, Main Agent settings, and the expandable built-in-tools list.
Voice and input	Speech-to-text, text-to-speech, and global shortcuts.
Screen and overlays	Cursor and speech-bubble controls.
Pickles and workspace	New-Pickle defaults, folder history, and archived sessions.
Notifications, permissions, and privacy	Optional work classification, new-Pickle notification defaults, macOS permissions, and local-data notice.
Advanced and diagnostics	Main-thread watchdog, picky shell command, and statistics-classification reset.

General

Setting	Values	Notes
App language	System default, English, 한국어	Most UI retranslates immediately. Some macOS-owned surfaces require relaunch.
Open Picky at login	Toggle	On by default for a new install, and also shown in the first-run checklist. Shows the state in System Settings > General > Login Items; Picky never turns it back on after you switch it off there or here.
Appearance	Light or Dark	Also available from the sidebar footer.
Hub font scale	90%–130%	Changes Hub controls and text. Report and terminal font scales are separate.
Update channel preference	Stable or Beta	Kept for settings-file compatibility. The installed app bundle determines which updates are eligible, so this setting does not move an installed app between release channels.
Check automatically / Check now	Toggle / button	Checks every 4 hours for a newer version. Checking only reads the version list; nothing is downloaded until you choose Update.

Pi accounts (Accounts and agents)

The Pi accounts card lists OpenAI Codex and Anthropic independently. It shows each current authentication state. Use Refresh to query both providers, Sign in or Reconnect to authenticate in a browser, and Disconnect to remove a configured provider after confirmation. A successful sign-in or disconnect reloads authentication for the current Picky/Pickle daemon sessions.

Picky shell command (Advanced and diagnostics)

Install picky shell command installs or uninstalls the picky launcher in /usr/local/bin (or the closest writable directory). After installing the shell command, use it to drive Picky from a terminal or hardware automation. The Picky main agent does not depend on this optional installation: primary agentd gives its existing bash tool an internal picky command automatically.

Ordinary terminals, resumed Pi sessions, Pickles, and subagents must omit --from-main; it is reserved for the live Picky main agent. On creation, it copies the daemon’s stored main request and desktop context, not the caller’s conversation. For self-contained coding or research, use picky pickle-create <title> --instructions <brief> --cwd <workspace> --no-context. Do not combine --no-context with --from-main: the current main route ignores --no-context. Context-free creation uses the external route and the configured new-Pickle completion-notification defaults.

picky submit "summarize the current screen"
picky pickle-create "Research" --instructions "Compare the open tabs" --group "Research"
picky whoami --json                       # from a Picky-hosted session
picky pickle-rename --self "Research"     # from the current Pickle
picky pickle-rename <session-id> "Research"
picky pickle-list --json
picky pickle-list --archived --query sentry
picky pickle-list --limit 20                        # first page plus "# total=..." line
picky pickle-list --limit 20 --cursor <token>       # next page, same options
picky pickle-archive <session-id>
picky pickle-unarchive <session-id>
picky pickle-notify <session-id>                    # show completion notifications
picky pickle-notify <session-id> --main off --macos on
picky pickle-steer <session-id> "focus on production impact"
picky pickle-abort <session-id>
picky pickle-group-list
picky pickle-group-list --include-archived
picky pickle-group-create "Research" <session-id>...
picky pickle-group-add <group-id> <session-id>...
picky pickle-group-remove-members <group-id> <session-id>...
picky pickle-group-remove <group-id>                # keeps members active
picky pickle-group-delete <group-id> --archive-members --confirm
picky ptt press
picky ptt release
picky settings-list --json
picky settings-get hud.dockVisible
picky settings-set hud.dockVisible toggle --display <display-id>
picky settings-set mainAgent.model "claude*sonnet"

picky pickle-create --group <name> places the new Pickle in the named dock group, creating that group when needed. If multiple groups share the same name, Picky uses the first matching group in dock order. picky pickle-list includes each grouped Pickle’s exact group ID and name. picky pickle-list --archived shows Pickles hidden from the dock; add --query <text> to search by ID, title, cwd, status, summary, or final answer. picky pickle-archive archives a Pickle, and picky pickle-unarchive restores it while it remains inside Picky’s archived-session retention window. picky pickle-group-remove removes only the group and keeps members active, while picky pickle-group-delete --archive-members --confirm removes the group and archives its members. picky pickle-group-list --json returns group IDs, names, colors, legacy collapsed state, and member session IDs for external scripting. The collapsed field is the fallback for displays without a saved group state, not the state of any specific display. Both picky pickle-list and picky pickle-group-list hide archived Pickles by default for every caller and output format, including JSON. Pass --include-archived to include them. Main-agent group lists use bounded text output.

picky pickle-create --wait keeps the terminal connection open until the Pickle completes, fails, or is cancelled, then prints its final answer. A blocked or waiting_for_input state does not finish the wait; resolve the request in Picky so the Pickle can continue. This option is unavailable to the Picky main agent.

picky pickle-list --json is the safe automation format. It returns { type: "pickleList", schemaVersion: 1, sessions: [...], total, nextCursor }. Every session contains only id, title, status, createdAt, updatedAt, normalized archived, and compact artifacts; cwd, archivedAt, and dockGroup appear when available. Artifacts contain id, kind, title, optional url, and updatedAt. Dock groups contain id, name, color, and collapsed. Session messages, logs, tool previews, final answers, local paths, queue text, changed files, and artifact paths are deliberately excluded.

Existing consumers of .sessions[].id, title, status, or artifact links should stay on --json. Legacy scripts that require session details omitted above must explicitly migrate to picky pickle-list --raw-json. That flag returns the former filtered session snapshot and may expose sensitive session details. It is not an authoritative message journal: the app bridge can return messages: [] with messageJournalAvailable: false. Activity histories are also omitted: tools and logs and subagentRuns are empty, and asyncTasks and completionTickets are absent. Archive selection, query filtering, paging, total, nextCursor, and dock-group enrichment are identical in both JSON modes.

picky pickle-list pages with --limit <count> and --cursor <token>. The first page keeps Picky’s recent-activity order, so a running Pickle stays near the top. Later pages continue through the remaining Pickles by creation time, newest first, and skip the ones already shown. total is the number of Pickles that match the archive scope and --query when the command runs, across all pages: non-archived Pickles by default, only archived ones with --archived, and both with --include-archived. nextCursor is null on the last page. Otherwise pass it back with --cursor and the same archive and query options; a cursor from different options exits with code 64. The cursor remembers the first page’s IDs as short hashes and the last row’s creation time, so a full walk returns every Pickle that exists throughout it exactly once, even while running Pickles update. A Pickle created or restored during the walk can fall before the cursor and is not returned; start again to include it. Each page fetches the whole list from Picky again, so walk every page only when you need the complete list. Text output adds one final # total=N scope=... showing=A-B; next: ... line when --limit or --cursor is given, and always for the main agent. The main agent receives at most 20 rows per page (10 by default) and cannot use JSON modes, so it reads the count from that line and follows the cursor to list everything. This change minimizes CLI stdout only; the local app/daemon bridge still supplies the session summary used for filtering.

picky pickle-notify <session-id> prints one Pickle’s two completion channels from section 8.9: main (report completion to the main agent) and macos (macOS notification). Pass --main on|off and/or --macos on|off to change them; an omitted channel keeps its value, and a value that already matches is not sent again. The change goes through the Pickle’s owning daemon, just like the composer and conversation-menu toggles, and appears in the HUD. It never changes the new-Pickle defaults in Settings. Any caller may use it, including archived Pickles; the main agent itself has no notification settings. --json returns { schemaVersion: 1, id, notifications: { main, macos }, changed }. Invalid values exit with code 64 and an unknown session with code 1.

Caller identity and Pickle names

picky whoami --json returns { schemaVersion: 1, kind, id, name, status, cwd, createdAt, group }. The kind is picky or pickle; group is { id, name } or null. The main agent has no Pickle creation date, so its createdAt is null. Conversation messages, tool output, and caller-binding values are excluded.

Identity comes from the current Picky-hosted bash or bash_async execution. An ordinary terminal or subagent cannot claim the parent session with --from-main. Missing, inherited, or expired caller context produces an error instead of falling back to the selected Pickle. /new and runtime replacement invalidate the old context. whoami does not start or resume an agent.

picky pickle-rename <session-id> "<name>" works from an ordinary terminal. Inside a Pickle, picky pickle-rename --self "<name>" uses the validated caller instead; do not combine --self with an ID. The main agent cannot rename itself. Add --json for { schemaVersion: 1, id, name, revision } containing the saved result.

Names are trimmed, limited to 200 Unicode code points, and cannot contain line breaks or control characters. Duplicate names are allowed. Renaming preserves work, unanswered questions, queued inputs, and archive state. It changes Picky’s display name, not the Pi session file. A user-assigned name takes precedence over Pi auto-naming until /new resets the Pickle. The title editor and /name in a Pickle conversation use this same metadata-only operation.

An archived or detached Pickle can be renamed without resuming it. If Picky cannot confirm exclusive ownership during a daemon transition, the command fails rather than writing another owner’s state. A connection failure after saving leaves the result unconfirmed; check picky pickle-list --include-archived before retrying. The CLI does not retry a rename automatically. Picky keeps spawning and deletion blocked while the owner’s write remains unconfirmed. If the owner never replies and those actions remain blocked, reopen Picky after checking the saved name.

CLI settings control

picky settings-list, picky settings-get <key>, and picky settings-set <key> <value> read and change a small allowlisted subset of Picky settings while Picky.app is running (the commands fail with a clear error when the app is not connected). The current keys are:

Key	Type	Notes
hud.dockVisible	bool, toggle	Optional --display <id> targets one display; without it, all displays change together. A display ID that is not currently connected is stored as an offline override and takes effect when that display returns.
hud.dockSizePreset	enum	s, m, l. Legacy default for displays without a saved size. Resizing a dock directly saves a display-specific size that this default does not overwrite.
cursor.visible	bool, toggle	Shows or hides the Pi cursor overlay.
mainAgent.model	string pattern	Applied to the running main session; the CLI reports saved but not applied: <reason> if the daemon rejects or times out.
mainAgent.thinkingLevel	enum	Same applied/pending semantics as the model key.
mainAgent.fastMode	bool, toggle	Provider fast mode for the main agent: faster replies at a higher price, supported models only. Because it costs more, only you can change it; the main agent cannot.
pickleAgent.model	string pattern	Affects newly created Pickles only.
pickleAgent.thinkingLevel	enum	Affects newly created Pickles only.
notifications.newPicklesNotifyMainOnCompletion	bool, read-only	New-Pickle default for reporting completion to the main agent; change it in Settings.
notifications.newPicklesNotifyMacOSOnCompletion	bool, read-only	New-Pickle default for macOS completion notifications; change it in Settings.

settings-list prints each key’s type, allowed values, and current value; --json returns the full catalog for scripting. settings-set responses distinguish persisted (written to settings.json) from applied (live in the running app/daemon). API keys and other sensitive fields are intentionally not exposed through the CLI.

The Picky main agent can also run these commands itself: asking Picky to “hide the dock”, “turn off the cursor”, or “switch the model” changes the setting through the same allowlist. The agent is instructed to change settings only when you explicitly ask.

Shortcuts (Voice and input)

Setting	Default	Notes
Push to Talk	Control + Option	Hold to start voice; release to send.
Quick Input	Double-tap Control	Opens quick text composer near cursor.
Focus Pickle	Left Command + Right Command	Opens the unread-first Pickle on the cursor’s display and gives its HUD keyboard focus.

Use Change, then Save or Cancel. Conflicts are rejected. Reset to defaults restores all three defaults.

Main Agent (Accounts and agents)

Main agent starts with the agent-name editor, followed by cards for workspace and instructions, model and reasoning, Task models, screen capture, armed-Pickle delivery, and runtime paths. The cards keep the controls visible while their summaries and details explain what each choice affects.

Setting	Values / behavior
Main agent working folder	Applies to captured Picky context and the next Picky session. Defaults to the seeded Picky workspace at ~/Library/Application Support/Picky/Workspace. Must be an existing directory. See Customizing the Picky workspace below.
Pi binary	Optional path to the pi executable. Leave empty to auto-discover via PI_CODING_AGENT_DIR/bin/pi, then PATH (which pi), then ~/.pi/agent/bin/pi. Used when Picky runs pi install/remove; install/remove actions pick it up immediately.
PI_CODING_AGENT_DIR	Optional Pi coding-agent directory for Pi sessions and extension/skill installs. Leave empty to use the launch environment’s PI_CODING_AGENT_DIR, then fallback to ~/.pi/agent. Must be an existing directory when set. Extension/skill installs pick it up immediately; running Picky/Pi sessions apply it after restarting Picky.
Pi model	Automatic or a pinned model pattern.
Reasoning level	Off, Minimal, Low, Medium, High, Extra High, Maximum. Maximum appears only for Pi models that support it.
Fast mode	Off (default) or On. Asks the provider for faster replies at a higher price, and applies only while the main model supports fast mode (the same models as the Pickle lightning button). Disabled when the selected model is known not to support it.
Task models	One model and reasoning level for each Task level: Fast (simple, well-defined work), Balanced (most work), and Powerful (hard or broad work). When a Task starts, a lightweight model reads its instructions and picks the level; that model can’t be changed. Automatic follows the account of Picky’s own model, and the menu shows what it runs now. Fast, Balanced, and Powerful use Low, Medium, and High reasoning on gpt-6-luna, gpt-6-sol, and gpt-6-astra for ChatGPT and OpenAI accounts, or on Claude Haiku, Sonnet, and Opus for Anthropic; other accounts use Picky’s own model and change only the reasoning level. Choosing only a model keeps the level’s automatic reasoning. Preset fills all three levels at once: Claude subscription uses Claude Haiku (High), Opus (Medium), and Opus (High); OpenAI subscription uses gpt-6-luna (High), gpt-6-sol (Medium), and gpt-6-sol (High). Changing any level afterward shows the preset as Custom. Changes apply to Tasks that start next. If you’re signed out of a chosen model, Tasks at that level don’t start and Picky says why.
Screen context	All screens or Focused screen only. Default is Focused screen only so Picky captures only the display the cursor is on — plus any display you draw on during that turn.
Armed Pickle delivery	Follow-up (default) or Steer. Controls how Push-to-Talk and Quick Input are delivered when a Pickle is explicitly armed as the screen-context target. Follow-up waits until the Pickle is idle; Steer interrupts the current turn at the next steering point.
Send screenshots only when drawn	Off (default) or On. When On, Picky attaches a screenshot to the model turn only if you marked the screen with click and drag during Push-to-Talk or Quick Input. Screen capture still runs locally so the ink overlay can render on top, but the screenshot is omitted from what the model sees. Off keeps the always-attach behavior.
Screenshot quality	1× 1280 px, 1.5× 1920 px, 2× 2560 px longest edge. Captured screenshots are written to the per-user temporary directory (FileManager.default.temporaryDirectory/Picky/Screenshots), not the durable Application Support tree.
Additional instructions	Extra standing instructions baked into the Picky bootstrap; apply on next Picky session/relaunch.

When saved changes require a fresh process (currently the effective PI_CODING_AGENT_DIR for running Picky/Pi sessions), the footer action changes from Quit to Restart so you can apply them without manually reopening Picky.

Agent name

The name belongs to this Mac installation and is shared with paired phones. It does not rename the app, your Pickles, the picky CLI, or the internal picky / main identifiers.

• Edit Agent name: Save changes and Cancel appear while the field differs from the saved name. Cancel discards only the unsaved edit; leaving the field does not save it. When no edit is open and the saved name is not Picky, Reset to Picky saves the default name.
• Names support 1–24 characters, including Korean and emoji, up to 256 UTF-8 bytes. Leading/trailing whitespace is removed and Unicode is normalized. Empty names, internal line breaks, tabs, and hidden control characters are rejected. Names do not need to be unique.
• A saved name updates sender labels and remote room titles. Once the agent confirms receipt, new replies use it; the current response, recording, speech playback, conversation, and background work continue unchanged. While disconnected, the app keeps the saved name and applies it after reconnection. A failed apply can be retried without saving again.
• Earlier message text and delivered notifications are not rewritten. Future phone notifications use the current name, which may appear on the lock screen. The name can also be sent to the selected AI provider and, where supported, the transcription provider as a recognition hint. Apple Speech and ElevenLabs do not use this hint.
• A malformed name field displays as Picky without rewriting the file on load. An explicit later settings save writes that fallback alongside your requested changes.
• An unreadable settings file is not treated as a new install. Fix the file and use Retry; the name editor does not delete or replace it. Other invalid settings, such as a missing workspace folder, must also be corrected before saving.
• Change the name in Hub, not in AGENTS.md, a natural-language request, or picky pickle-rename. Resetting the conversation does not reset the name. A session resumed directly in an external Pi terminal does not receive Picky’s current-name contract automatically.

Customizing the Picky workspace

The Picky main agent runs in a workspace folder so Pi automatically loads any AGENTS.md, .pi/extensions, .pi/skills, and .pi/prompts you drop in there. Picky seeds a default AGENTS.md with the always-on persona on first launch. How Picky chooses between a direct answer, a Task, and a Pickle is built in (see 5.2); add rules to AGENTS.md only for specific kinds of work, such as “always hand hotfixes for this repo to a Pickle”.

Default location:

~/Library/Application Support/Picky/Workspace

What lives there:

• AGENTS.md — Picky’s persona and rules for specific kinds of work. Edit freely; Picky never overwrites your changes. Delete the file and relaunch Picky to reseed the default. An unedited default from an earlier release is updated to the current default automatically.
• .pi/extensions/, .pi/skills/, .pi/prompts/ — optional Pi customization that augments Picky exactly the way Pi loads them in any other cwd.

The seeded AGENTS.md instructs the main agent to keep itself in sync with how you talk to Picky:

• Persistent rules and preferences (“from now on do X”, “apply this rule”, “add/update/remove this instruction”) — the agent follows the request for the current turn and edits AGENTS.md directly under the most relevant section, then tells you which section was changed.
• Pickle execution guidance (default cwd or repo path for a kind of task, fixed procedures/checklists, preferred skills/MCPs, naming conventions, what to include in instructions) — written into a dedicated ## Pickle execution section so it is loaded on every main-agent turn instead of stashed in memory.
• One-off facts and scratch notes — routed to the built-in memory tool when one is available; otherwise the agent creates a sibling file next to AGENTS.md (for example NOTES.md or notes/<topic>.md) and adds a short pointer under a ## Notes section in AGENTS.md.

In practice you can shape Picky just by talking to it (“always start Pickles for the picky repo from ~/Projects/picky and follow the AGENTS guide there”) and let Picky persist the rule. You can still hand-edit AGENTS.md whenever you want full control.

To run Picky with a completely different persona or workflow set, change Hub → Settings → Accounts and agents → Main agent → Main agent working folder to any folder that contains its own AGENTS.md and .pi/* subdirectories.

Pickles and workspace

Setting	Values / behavior
Default cwd	Default working directory for new Pickles. Must be an existing directory.
Pickle model	Automatic or pinned initial model for newly-created Pickles.
Reasoning level	Automatic, Off, Minimal, Low, Medium, High, Extra High, Maximum. Applies as the initial setting for new Pickles; Maximum requires a Pi model that supports it.
Archived sessions	Footer disclosure (hidden when empty). Expands to the same restore/delete list available from the HUD, so you can manage archives without leaving Settings.

New Pickles created through the CLI also use the current Pickle model and reasoning defaults. Resumed Pickles keep the settings saved in their transcript. Running Pickles can still cycle model/thinking independently from these defaults.

Built-in tools (Accounts and agents)

Built-in capabilities that add dedicated agent context can be disabled here. Pickle creation, listing, steering, abort, archive, and dock-group management use the local picky CLI and are always available, so they do not appear as toggles. Screen pointing & drawing controls all agent-authored pointer and shape overlays as one capability.

Tool changes apply to the main agent immediately and interrupt any in-progress turn. Pickles that started before the change keep their existing tool list until the next turn.

Voice (STT & TTS, Voice and input)

Picky supports Apple/macOS built-in, OpenAI direct (api.openai.com), Azure OpenAI, and ElevenLabs for speech recognition and synthesis. Groq is an additional transcription-only provider with a free tier. Edge TTS (Online) is an additional playback-only, explicit opt-in provider; it sends spoken response text to Microsoft Edge Read Aloud through local picky-agentd. Each provider’s relevant settings appear only when that provider is selected.

Setting	Values / behavior
STT provider	Apple Speech (default), Groq (free), OpenAI, Azure OpenAI, ElevenLabs. Each provider shows a one-line note on cost and where speech is sent. Apple Speech uses the on-device SFSpeechRecognizer (offline) and offers a Switch to Groq shortcut. Groq uses Whisper through api.groq.com/openai. OpenAI uses gpt-4o-transcribe against api.openai.com. Azure OpenAI uses your deployment URL. ElevenLabs uses scribe_v2 against api.elevenlabs.io (the legacy scribe_v1 is deprecated as of 2026).
Enable spoken replies (TTS)	On/off. When off, text replies still appear but audio playback is skipped. Long narrated replies can begin playing sentence by sentence while the remaining response is still streaming. TTS reads rendered Markdown text rather than syntax markers (**, headings, list prefixes, or link destinations); inline code text is read, while fenced code blocks are skipped.
TTS provider	macOS Speech (default), OpenAI, Azure OpenAI, ElevenLabs, Edge TTS (Online, explicit opt-in; playback only). macOS Speech uses the system NSSpeechSynthesizer voice. OpenAI uses gpt-4o-mini-tts against api.openai.com. ElevenLabs uses eleven_v4 with the female voice Talia against api.elevenlabs.io by default. Edge TTS sends spoken response text to Microsoft Edge Read Aloud through local picky-agentd.
Open macOS Speech Settings	Opens the system Spoken Content settings for local TTS voice selection.

Groq STT fields (when STT provider = Groq):

• API key (gsk_…), saved in the macOS Keychain rather than settings.json. A new key applies to the next dictation. Leave empty to fall back to GROQ_API_KEY from the environment. When no key is entered, Settings shows a three-step guide and an Open Groq console button (console.groq.com/keys).
• Check connection sends one second of silence to Groq and reports success with the response time, a rejected key (401/403), a usage limit (429), or a network/HTTP failure. Picky does not switch to Apple Speech automatically when the limit is reached.
• Model: Accuracy first (whisper-large-v3, default) or Speed first (whisper-large-v3-turbo). Both share the same free limits.
• Spoken language: Detect automatically (default), Korean, English, Japanese, or Chinese.
• Free tier (Groq’s published limits when this feature shipped): 2,000 requests and 8 hours of audio per day, 20 requests per minute. Limits apply per Groq organization.

Frequent words (Groq, OpenAI, and Azure STT):

• Frequent words — comma- or newline-separated spellings sent as transcription hints, default Picky, Pickle. They are placed before automatic hints so they are never dropped.
• Also send the current app and window names — on by default. When off, only the frequent words are sent as hints.

OpenAI STT fields (when STT provider = OpenAI):

• OpenAI STT API key (sk-…). Like Groq, Settings shows a key guide, an Open OpenAI console button, and Check connection.
• OpenAI STT model — leave blank for the recommended gpt-4o-transcribe default
• OpenAI STT preferred language — ISO-639-1 code or empty for auto detect
• OpenAI STT base URL — empty uses https://api.openai.com. Set this to point Picky at any OpenAI-compatible HTTP server (LocalAI, openai-edge-tts, Together, Groq, self-hosted inference, etc.). A trailing /v1 is stripped automatically. Picky speaks the standard /v1/audio/transcriptions protocol — proxy stability is your responsibility.

OpenAI TTS fields (when TTS provider = OpenAI):

• OpenAI TTS API key (sk-…; leave empty to reuse the STT key, then the OPENAI_API_KEY env)
• OpenAI TTS voice — alloy (default), ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse, marin, cedar
• OpenAI TTS model — leave blank for gpt-4o-mini-tts
• OpenAI TTS base URL — same semantics as STT base URL above

Azure STT fields (when STT provider = Azure OpenAI):

• Azure STT transcription URL — full deployment URL from the Azure portal
• Azure STT API key
• Azure STT preferred language

Azure TTS fields (when TTS provider = Azure OpenAI):

• Azure TTS speech URL
• Azure TTS API key — leave empty to reuse the STT key
• Azure TTS voice

ElevenLabs STT fields (when STT provider = ElevenLabs):

• ElevenLabs STT API key
• ElevenLabs STT model — scribe_v2 (default); scribe_v1 is deprecated
• ElevenLabs STT language — ISO-639-1 or 639-3 code, or empty for auto detect

ElevenLabs TTS fields (when TTS provider = ElevenLabs):

• ElevenLabs TTS API key — leave empty to reuse the STT key, then ELEVENLABS_API_KEY from the environment
• ElevenLabs TTS voice ID — leave blank for ELEVENLABS_VOICE_ID from the environment, then OZ0L6eISlOejga3XjDFt (Talia - Warm Soft Guide, a female voice ElevenLabs suggests as the replacement for its retiring Sarah default voice)
• ElevenLabs TTS model — leave blank for eleven_v4 (90+ languages, including Korean). ElevenLabs only serves it through POST /v1/text-to-dialogue, so Picky switches to that API and sends the voice ID inside the request instead of the URL. Other models, including eleven_v3, keep using /v1/text-to-speech/{voice_id}. eleven_v4_turbo is WebSocket-only and is not supported. The whole clip is downloaded before playback, so eleven_v4 starts speaking later than the Flash models; ElevenLabs recommends keeping a single dialogue request under 2,000 characters
• ElevenLabs TTS output format — leave blank for mp3_44100_128
• ElevenLabs TTS base URL — leave blank for https://api.elevenlabs.io

Edge TTS (Online, explicit opt-in; playback only). Choose Edge TTS (Online) in the TTS provider picker, then select a language and voice. Picky sends spoken response text through its local picky-agentd adapter to Microsoft Edge Read Aloud. If the synthesis endpoint returns HTTP 403, Picky retries once on the alternate Microsoft endpoint. This works in both directions, and a successful endpoint is reused until the daemon restarts or that endpoint returns 403. This unofficial service may change or become unavailable; Picky falls back to macOS Speech if synthesis fails. macOS Speech remains the default. Picky uses the MIT-licensed msedge-tts package for this adapter.

Screen, overlays, notifications, and privacy

Hub → Settings → Screen and overlays contains the cursor and speech-bubble controls. Hub → Settings → Notifications, permissions, and privacy contains new-Pickle notification defaults, optional statistics classification, macOS permissions, and the local-data notice.

Cursor

Setting	Default	Meaning
Show Picky Cursor	On	Shows the cursor buddy overlay.
Smooth cursor follow	On	Enables springy cursor-follow animation.
Idle animations	On	Enables idle cursor animations.

If Show Picky Cursor is off, smooth follow and idle animations are disabled. Picky still shows a minimal waiting indicator near the system cursor while a cursor-side request is in flight, then hides it again when the response arrives or the request ends.

While the Mac App Store is the frontmost app, Picky temporarily hides the cursor overlay and brings it back when you switch away. macOS suppresses secure purchase confirmations whenever another app’s window overlaps them, so this keeps App Store purchase sheets working while Picky runs.

Bubbles

Setting	Default	Meaning
User STT recognition	On	Shows recognized speech bubble.
Picky reply text	On	Shows Picky reply bubble.

Alerts

Setting	Default	Meaning
Report new Pickles to main agent when complete	Off	Default main-agent completion reporting for newly created Pickles.
Notify in macOS when new Pickles complete	Off	Default macOS completion notification for newly created Pickles.
On failure	On	Show banner when a session fails.
On input request	On	Show banner when a session waits for user input.

The two completion defaults are independent and do not modify existing Pickles. Change an existing Pickle’s controls in its composer or conversation menu. Upgrading preserves the former On success setting as the macOS default for future Pickles.

Updates (General)

Control	Values / behavior
Update channel preference	Stable or Beta. This legacy saved preference does not change the installed build’s release channel or update eligibility. Install the matching release artifact to move between Stable, Beta, or Alpha.
Check automatically every 4 hours	Toggle that enables the periodic check. The check only reads the available version; it never downloads.
Check Now	Manual update check when available.

When a newer version exists, the Dashboard shows it under the greeting. Update checks again and downloads the newest version available at that moment, so a release published after the notice appeared is the one you get. The download is reported on the card; when it finishes, Picky asks before restarting if any Pickle is still responding or has a question waiting for your answer. Restarting stops those responses and cancels those questions, and conversations are kept. If you choose Later, the card stays hidden for that version.

A version Picky downloaded before this behavior changed still installs the next time you quit.

Alpha builds do not expose Sparkle updates; install the next trusted alpha package manually.

Advanced and diagnostics

This group includes the main-thread watchdog, Install picky shell command, and Reset statistics classification. Resetting classifications asks for confirmation and affects only the locally stored work-classification data; it does not delete Pickles or their conversation history.