Configure
Settings reference
Open Settings from the gear in the title bar. Settings can't be changed while recording.
#Microphone
| Setting | Default |
|---|---|
| Record my voice | On |
| Microphone | System Default |
| Record the other side too (meetings) | Off |
#Transcription
| Setting | Default |
|---|---|
| Language (spoken) | Auto |
| Engine | On device (free) |
| Model (on device) | large-v3-turbo (recommended) |
| Endpoint Base URL / Model (compatible) | empty |
| OpenAI API key / Endpoint API key (optional) | not set |
| Cost cap | Up to $1 per review |
#Storage
| Setting | Default |
|---|---|
| Keep recordings: 7 days / 30 days / Forever | 7 days |
| Stay on the feedback screen after stopping | Off |
#Agents
| Setting | Default |
|---|---|
| Start When a Project Opens | Claude Code, Codex (pick any supported agents, or none) |
| Show <agent> in menus | On for every agent |
| Start agents without permission prompts | On: Claude Code starts with --dangerously-skip-permissions, Codex with --dangerously-bypass-approvals-and-sandbox (details) |
| Notify me when agents finish or need me | Off (details) |
| Command / arguments (per agent) | The agent's own command (for example claude, codex, gemini) / --chrome for Claude Code, none for the others |
| Custom Agents | None (Add Custom Agent registers any CLI) |
| Instructions for Agent | Built-in text (variables) |
| Terminal shell (Windows) | PowerShell: PowerShell 7 (pwsh) when installed, otherwise Windows PowerShell. It keeps your command history across tabs and restarts. cmd.exe is the other choice (agents.windowsShell in settings.json). Applies to tabs opened afterwards |
#Switch on usage limits
| Setting | Default |
|---|---|
| Switch automatically when a usage limit is reached | On |
| Count an account as at its limit from | 95% |
| Try another account of the same agent first | On |
| Agent order | Claude Code, Codex, Gemini CLI |
| Move back to a higher agent when its limit resets | Off |
In Settings → Accounts. Work is handed over through .ferret/handoff.md in the project. See Keep working at usage limits.
#Accounts, service CLIs, appearance, language
- Accounts: see Accounts and usage.
- Service CLIs: install and sign in to service CLIs. See Service CLIs.
- Import from browsers: bring passwords (from an exported CSV) and history into the built-in browser. See Import passwords and history.
- Appearance → Theme: System (default), Light, Dark.
- Language → Interface: System (default; follows the OS language when Ferret has it, English otherwise) English or 日本語.
From the footer: terminal position (right / bottom) and the microphone toggle.
#settings.json
Everything above is stored in ~/.ferret/settings.json (same path on every OS), with a JSON Schema next to it. You can edit it while the app is running, by hand or with your coding agent; changes apply immediately. See Configure with settings.json.