# Frog configuration: text settings, JSON rules, and sync

Canonical page: https://frog.beffa.xyz/docs/configuration/
Updated: 2026-10-26

Frog uses two portable files in ~/.config/frog/: config for commented key = value settings, and config.json for complex rules, connections, and custom model definitions. Private data and credentials stay separate.

These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release.

## Export, edit, and import your setup

Export creates a complete version-1 JSON document containing the effective text preferences and complex configuration. The split live config.json alone is not a complete export. Import validates the document, backs up the existing JSON and text files, then writes both local files. Invalid imports leave the existing setup untouched. The import limit is 4 MB; credentials and private data are excluded.

1. Open Settings → Configuration and choose Export to save the current setup as JSON.
2. Edit the exported file in a text editor. Start from a real export so the existing rule identifiers and model selections are preserved.
3. Return to Settings → Configuration and choose Import.
4. Review the imported setup. On another Mac, install the selected apps and model downloads, supply provider credentials, and grant permissions as needed.

## What is included in a config file?

Direct provider API keys stay in macOS Keychain; installed CLIs own their credentials. Saved history, local statistics and its collection switch, clipboard entries, toolkit documents, script output, usage records, the command bar’s learned choices, App cleaner’s Put Back list, downloaded model weights, permissions, login startup, and device-local storage settings are not portable configuration. Rule instructions and connection endpoints are readable in an export, so inspect it before sharing.

- config: appearance, semantic theme colors, feature choices, global shortcuts, model defaults, recording/history preferences, and menu-bar settings.
- config.json: writing and audio rules, explicit per-rule models, provider connections, application/window/system actions, individual rule shortcuts, custom models, and additional internal fields.
- Mr. Usage display choices use usage.provider, usage.range, usage.metric, usage.all-devices, usage.login-source, usage.claude-accounts, usage.claude-accounts-view, and usage.claude-accounts-menu-bar in config.
- Explain uses explain.context, explain.notes, explain.notes-folder, explain.notes-mode, explain.notes-file, explain.notes-open, explain.selection-bubble, and the explain.bubble-* keys. Answer rules are in config.json.
- Windows uses windows.gap, windows.cycle-sizes, windows.portrait-thirds, windows.respect-stage-manager, windows.layout-picker, windows.drag-to-snap, windows.restore-on-drag, windows.zone-overlay, and windows.zone-grid.
- App cleaner uses cleaner.possible-matches; command-bar.learn-choices turns on Learn from your choices.
- Installed-tool connections retain the tool kind and model ID; @default selects the CLI default, without serializing executable paths or login state.

## Feature settings and private documents

Use Features to turn tools on and off, and each tool’s own page for its settings: Models for downloads, model memory and storage, providers, and installed coding tools; Dictation for recording preferences; Clipboard for its Quick paste shortcut; and Stay awake for session and access controls. Settings includes appearance, history retention, local Statistics, permissions, and configuration editing/reload and import/export.

Feature keys use names such as feature.command-bar, feature.explain, feature.windows, feature.cleaner, feature.clipboard, feature.usage, and feature.menu-bar, with true or false values. These optional tools default off. Disabling a tool retains its settings and documents but removes commands and stops its work; clipboard contents are cleared. Restore an active Stay awake session before disabling that feature through Reload.

Notes and script text are stored separately in ~/.config/frog/Toolkit/toolkit-documents.json. This is a private local document store, not part of config.json or its export. Use an item’s Export action to save its text explicitly. Copying configuration does not move these documents or the original files that notes refer to.

Frog 1.0.39 retired feature.snippets, feature.shelf, and feature.quick-actions. A file that still sets them loads, turns Notes on when snippets or shelf was on, and leaves them out the next time Frog saves it.

## Example: text settings and appearance

Put this example in ~/.config/frog/config. Keys are case-sensitive; booleans are true or false. A # starts a comment except at the start of a hex color value. Quote strings containing # or quotes as JSON strings. Duplicate keys, unknown keys, and invalid values produce line-numbered errors. Remove an assignment to restore its default.

Themes are minimal, frog, tokyoNight, catppuccin, nord, gruvbox, dracula, rosePine, solarized, everforest, and graphite. Without a theme line Frog uses minimal, a gray and white theme with a gray accent. Each supplies light and dark palettes. Override individual palette.light.<role> or palette.dark.<role> values with six-digit RGB colors. Roles include background, sidebar, surface, inset, border, text, muted, accent, good, warning, and critical; on-accent is still accepted but no longer used.

transparency and popup-transparency independently range from 0 (opaque) to 1. The main window and popups use native behind-window backdrop blur with a readable tint; text is not blurred. macOS Reduce Transparency or Increase Contrast makes surfaces opaque without changing saved values. Global shortcuts accept readable names such as ctrl+alt+space; individual rule shortcuts remain in JSON.

```ini
# Basic settings in ~/.config/frog/config
appearance = system
theme = frog
transparency = 0.15
popup-transparency = 0

feature.command-bar = true
shortcut.command-bar = ctrl+alt+space
history-enabled = false
model-idle-seconds = 120

palette.dark.accent = #A3D8AF # optional color override
```

## Edit and reload the live configuration

There is no automatic file watcher. UI edits write the same files while preserving comments, ordering, whitespace, and unchanged value spellings. If either file or its symlink destination changed externally, UI saves stop and ask you to Reload rather than overwrite the edits. Invalid reloads leave the running configuration and files untouched; errors appear in the banner and Settings → Logs. Each file has a 4 MB limit.

On first use without a text config, Frog backs up a valid legacy config.json verbatim before splitting out its basic settings. Older ~/Library/Application Support/Frog/configuration.json is left intact; Frog reads it only until config.json has existed on this Mac, and after that only through Import. Invalid or unsupported files are not silently overwritten. Changed or new imported provider connections receive fresh credential identities; matching identities, service types, and endpoints retain credentials.

1. Open Settings → Configuration → Open config to edit ~/.config/frog/config. Complex rules and connections live in config.json in the same folder.
2. Save your changes, finish any active request or recording, then choose Reload in Frog.
3. Review the result. Valid changes apply immediately, including theme, features, shortcuts, history limits, and model idle policy. Explicit per-rule model choices are not replaced by global defaults.

## Sync both files with your dotfiles

Track both config and config.json, for example with chezmoi. Frog follows file and directory symlinks, atomically replacing the resolved file destinations while preserving the links. Comments and formatting in the text config survive UI edits. Local recovery backups need not be synced.

After chezmoi apply, choose Reload in Frog. Coordinate edits across Macs: each file is written atomically, but Frog does not provide a cross-file transaction or distributed sync/merge service. Model downloads, permissions, credentials, and private data still need their own device-local setup.

```sh
chezmoi add ~/.config/frog/config ~/.config/frog/config.json
```

## Portable menu-bar settings

feature.menu-bar enables the optional organizer and defaults to false. menubar.auto-hide defaults to true; menubar.auto-hide-seconds defaults to 10 and accepts 1–3600 seconds, including fractions. menubar.start-collapsed, menubar.permanently-hidden-section, and menubar.hover-to-reveal default to false. menubar.hotkey is optional and unassigned by default, for example ctrl+alt+m.

Actual macOS status-item positions remain on each Mac. Quit an existing Hidden Bar instance before enabling Frog’s organizer. The organizer is unsupported on macOS 27 and later.

- [Menu-bar arrangement and reveal controls](https://frog.beffa.xyz/docs/features/#menu-bar)

## Related guides

- [App shortcuts](https://frog.beffa.xyz/docs/app-shortcuts/)
- [Model providers](https://frog.beffa.xyz/docs/providers/)
- [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/)

## Source documentation

- [Text settings, JSON interchange, and configuration reference](https://github.com/t1llo/frog/blob/main/docs/configuration.md)