# Frog for macOS: complete documentation > Frog is a configurable native macOS toolkit with writing, Explain, dictation, window tools, command search, clipboard, notes, scripts, App cleaner, optional Mr. Usage, Stay awake, and System monitor, plus a frog command that AI agents can use, also to build plugins for you. Local AI runs on Apple silicon; cloud providers are optional. Official website: https://frog.beffa.xyz/ Source repository: https://github.com/t1llo/frog Download and release notes: https://github.com/t1llo/frog/releases/latest These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. This file contains the same guides published as HTML and Markdown under https://frog.beffa.xyz/docs/. Each guide includes its canonical URL, content update date, and source references. --- # Frog for macOS: toolkit features and guides Canonical page: https://frog.beffa.xyz/docs/ Updated: 2026-10-26 Frog brings everyday Mac tools into one native app. Choose the features you use: write and dictate with local or connected models, ask about selected text, arrange windows, find apps, keep reusable text, run saved scripts, uninstall apps, or check your AI usage. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Build your own set of tools Open Features to enable or disable a tool. Enabled tools appear in the sidebar; History, Models, Features, and Settings stay available below them. Newly added optional tools start off. Disabling a feature removes its navigation and commands and stops its owned work while retaining its settings. Every tool you turn on has its own page with all its settings: Writing, Explain, and Dictation; Windows for snapping and layouts; Window switcher, Clipboard, and System monitor; Stay awake for its session and access. Models brings Local models, Providers, and Installed tools together. Shortcuts groups Application and Other actions, and holds window layouts while Windows is off. Features only turns tools on and off. - [Choose and manage features](https://frog.beffa.xyz/docs/features/) - [Search with the command bar](https://frog.beffa.xyz/docs/command-bar/) ## Find, write, and organize from the keyboard Enable Command bar and press Control–Option–Space to search applications, available windows, Spotlight filenames, macOS settings, and enabled Frog tools. It also calculates, converts units, finds a small emoji collection, and runs enabled rules or saved scripts. Explain answers questions about text you select in another app, in a panel next to it, without replacing the text. Windows snaps windows to screen edges and corners and offers a layout picker. App cleaner moves an app and the files it leaves behind to the Trash after you review them. Notes provides local Markdown editing and preview, and a note can paste from the command bar with the date, time, and clipboard filled in. The command bar also cleans tracking parameters from a copied URL, encodes or decodes Base64, and generates UUIDs. Mr. Usage adds a separate menu-bar readout and popup for AI plan limits and token activity. Collection continues while enabled, including with the dashboard closed. Stay awake is an explicitly started, time-limited power session; enabling the feature does not start a session. System monitor shows CPU, GPU, disk, and power readings on its own page and in an optional System view of Frog’s menu-bar popup. ## Choose local models or connect a provider Internal models run inside Frog on Apple silicon after you download their weights. A fully local writing or dictation workflow can then work offline. External providers include local Ollama or LM Studio servers as well as cloud APIs such as OpenAI, Claude, and Gemini. Models → Installed tools also offers text models through supported Claude Code, Codex, and OpenCode CLIs using their existing login. Each rule chooses its own model. A CLI or cloud-backed rule follows that provider’s data policies; an installed tool is not necessarily offline. Frog itself has no required account or telemetry. ## What Mac do I need? Frog supports macOS 14 or later on Apple silicon and Intel Macs. Built-in speech and text inference requires Apple silicon. Intel Macs can use external providers and native toolkit features that do not require local inference. Most toolkit actions need no model or account. Cloud AI, model downloads, updates, and provider usage requests need a connection; local search and document tools do not need a cloud model. ## Keep your setup in readable files Frog keeps basic settings in ~/.config/frog/config as commented key = value text, with rules, connections, and custom models in config.json beside it. Edit through Settings → Configuration → Open config, then Reload. Sync both files with your dotfiles tools; a complete single-file JSON export is also available. Credentials, model weights, history, local statistics, clipboard entries, toolkit documents, usage records, and device-specific permissions stay separate. ## Feature guides - [Getting started](https://frog.beffa.xyz/docs/getting-started/): Install Frog on macOS 14+, choose local models or an external provider, review permissions, and run your first writing or dictation rule. - [Choose features](https://frog.beffa.xyz/docs/features/): Enable the Frog tools you use, find their pages, and understand what stops or stays saved when you disable a feature. - [Command bar](https://frog.beffa.xyz/docs/command-bar/): Use Control–Option–Space to search Mac apps, windows, files, macOS settings, and enabled Frog tools, calculate, uninstall apps, and learn from your choices. - [Writing rules](https://frog.beffa.xyz/docs/writing-rules/): Use Frog’s writing rules to proofread, rewrite, or translate selected text on macOS with custom instructions, model choices, and keyboard shortcuts. - [Explain](https://frog.beffa.xyz/docs/explain/): Ask about text you select in any Mac app with Frog’s Explain and read the answer in a panel next to it, with follow-ups, notes, and a selection bubble. - [Dictation](https://frog.beffa.xyz/docs/dictation/): Dictate into Frog using local speech models or an external transcription provider. Choose hold or toggle recording, transcript cleanup, and copy or paste. - [Local models](https://frog.beffa.xyz/docs/local-models/): Run Frog’s downloaded speech and text models locally on Apple silicon. Learn about Whisper, Parakeet, MLX text models, downloads, and offline operation. - [Model providers](https://frog.beffa.xyz/docs/providers/): Connect Frog to Ollama, LM Studio, OpenAI, Claude, Gemini, or a compatible endpoint. Learn how per-rule model choices and local versus cloud processing work. - [App shortcuts](https://frog.beffa.xyz/docs/app-shortcuts/): Use Frog’s application shortcuts to launch an app or bring it forward from the keyboard, and keep shortcut settings in a portable JSON configuration. - [Windows](https://frog.beffa.xyz/docs/window-management/): Arrange Mac windows with Frog’s Windows page: drag to screen edges, hold Shift for zones, pick a layout, or give its 23 layouts shortcuts. - [Window switching](https://frog.beffa.xyz/docs/window-switching/): Use Frog’s optional Command–Tab window switcher to choose individual Mac windows, search by title, and navigate recent windows from the keyboard. - [Clipboard](https://frog.beffa.xyz/docs/clipboard/): Enable Frog’s memory-only clipboard, use Shift–Command–V to search and paste formatted or plain text, and see how keys and passwords stay hidden. - [Notes](https://frog.beffa.xyz/docs/notes/): Write private Markdown notes on your Mac, and paste the ones you reuse, such as replies or a signature, from the command bar with the date, time, and clipboard filled in. - [Saved scripts](https://frog.beffa.xyz/docs/scripts/): Run saved zsh scripts explicitly in Frog with a 60-second timeout, bounded captured output, cancellation, and owned process-group cleanup. - [Mr. Usage](https://frog.beffa.xyz/docs/mr-usage/): Enable Frog’s separate Mr. Usage menu-bar readout, popup, and dashboard for Claude and OpenAI limits, token charts, costs, and credits while enabled. - [Stay awake](https://frog.beffa.xyz/docs/stay-awake/): Set up Stay awake in Terminal, start a timed session, and understand four-hour defaults, quit cleanup, low-battery stops, and restoring system sleep. - [System monitor](https://frog.beffa.xyz/docs/system-monitor/): Enable Frog’s optional System monitor to see CPU and GPU activity, disk space and throughput, battery power, and thermal state on its page or in the menu bar. - [App cleaner](https://frog.beffa.xyz/docs/app-cleaner/): Uninstall Mac apps with Frog’s App cleaner, together with the caches, settings, and services they leave behind. Review every item; everything goes to the Trash. - [AI agents](https://frog.beffa.xyz/docs/ai-agents/): Let Claude Code, Codex, Gemini CLI, pi, and OpenCode build Frog plugins for you, arrange windows, run your saved scripts, and read notes through the frog command. - [Plugins](https://frog.beffa.xyz/docs/plugins/): Add pages and command-bar commands of your own to Frog with plugins: small web pages that run in a sandbox and do only what you approve. - [Configuration](https://frog.beffa.xyz/docs/configuration/): Edit Frog’s commented key=value settings and JSON rules, reload changes, sync both files with chezmoi, or import and export a complete setup. - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/): Understand Frog’s local and cloud data flow, microphone recordings, Keychain credentials, optional history, model downloads, and offline operation. - [Frequently asked questions](https://frog.beffa.xyz/docs/faq/): Answers about Frog availability, feature switches, Explain, windows, App cleaner, local AI, clipboard, scripts, usage credentials, and power sessions. ## Related guides - [Getting started](https://frog.beffa.xyz/docs/getting-started/) - [Choose features](https://frog.beffa.xyz/docs/features/) - [Command bar](https://frog.beffa.xyz/docs/command-bar/) - [Configuration](https://frog.beffa.xyz/docs/configuration/) ## Source documentation - [Frog project and release notes](https://github.com/t1llo/frog) --- # Install and set up Frog on macOS Canonical page: https://frog.beffa.xyz/docs/getting-started/ Updated: 2026-10-29 Install the published Frog app, then choose the tools you want. These guides follow the current source; the availability note on each guide names the release they describe. There is no required Frog account. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Install Frog The published 1.0.42 app includes everything described in these guides. If you run an older version, check Settings → About and the release notes when comparing your app with them. 1. Open the GitHub releases page and download Frog-macOS.dmg for the latest release. A ZIP is also provided. 2. Open the DMG and drag Frog.app to your Applications folder. 3. Open Frog and follow the setup assistant. Its steps are optional, and you can return to them later. - [Download the latest Frog release](https://github.com/t1llo/frog/releases/latest) ## Choose how to run your models For an offline setup on Apple silicon, download a speech model for dictation and a text model for writing or transcript cleanup. The setup assistant recommends Whisper Large v3 Turbo and Qwen3 1.7B (4-bit), approximately 1.6 GB of downloads in total. Download size is not a memory requirement or a performance guarantee. Open Models → Local models for downloads, Models → Providers for local servers or cloud services, or Models → Installed tools to use a supported coding CLI’s existing login. Use model adds its text model to the rule selectors without a Frog API-key form. You can also import a complete Frog JSON export or sync both live configuration files. Credentials, downloaded weights, and macOS permissions are separate. Non-AI tools need no model. - [Installed tools and provider setup](https://frog.beffa.xyz/docs/providers/#installed-tools) - [Configuration files and reload](https://frog.beffa.xyz/docs/configuration/) ## Choose your tools Enabling Stay awake makes its page available; starting a power session is a separate action. Finish its guided access setup before starting your first session. 1. Open Features, pinned at the bottom of the sidebar. 2. Enable the optional tools you want, such as Command bar, Explain, Windows, or Mr. Usage. Their pages appear in the sidebar. 3. Open a tool’s page to configure it, from the sidebar or with Open beside it in Features. Command bar starts with Control–Option–Space; Clipboard’s Quick paste starts with Shift–Command–V. 4. Return to Features to disable a tool and stop its work. Your configuration and saved documents remain; temporary clipboard history is cleared. ## Review the permissions for the features you use Accessibility access lets Frog work with selected text and individual application windows. Microphone access is needed for recording dictation. Review the permissions from the setup assistant or Frog’s settings and macOS System Settings. The window switcher uses Accessibility rather than screenshots and does not need Screen Recording permission. Recording begins when you invoke an audio rule, rather than running continuously in the background. ## Try a writing rule To revisit setup, open Settings → General → Setup assistant. For version-specific behavior, use the release notes that accompany your installed build. 1. Open Writing and choose a text rule such as proofreading. Select an available text model and record a shortcut if the rule does not have one. Try opens an in-app text test. 2. Write a short draft in an editable field in another app, then select the words you want to change. 3. Invoke the rule’s shortcut and wait for the result. If automatic replacement is unavailable, paste the result from the clipboard. ## Related guides - [Choose features](https://frog.beffa.xyz/docs/features/) - [Local models](https://frog.beffa.xyz/docs/local-models/) - [Writing rules](https://frog.beffa.xyz/docs/writing-rules/) - [Stay awake](https://frog.beffa.xyz/docs/stay-awake/) ## Source documentation - [Installation instructions](https://github.com/t1llo/frog#install) - [Provider and first-launch documentation](https://github.com/t1llo/frog/blob/main/docs/providers.md) --- # Choose your Frog toolkit: features and navigation Canonical page: https://frog.beffa.xyz/docs/features/ Updated: 2026-10-26 Features is the control center for your toolkit: a list that switches individual tools on or off. Every tool that is on gets its own page for daily work and configuration. You can keep Frog focused on a few tools or enable a broader workspace. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Enable a tool and open its page Command bar, Explain, Windows, Mr. Usage, Notes, Scripts, Menu bar, System monitor, and App cleaner are optional tools and start off. Clipboard is separately opt-in and also starts off. Existing writing, dictation, shortcuts, and window preferences are preserved when adopting the toolkit. Stay awake’s feature availability and its active session are separate. Its page can be available while the sleep setting remains off; a session never starts automatically at launch. 1. Open Features, pinned at the bottom of the sidebar. 2. Search by a tool’s name or description, then turn on its switch. 3. Choose Open beside it or select the new sidebar item. 4. Configure that tool’s models, shortcuts, or documents on its own page. Every setting of a tool is on its page; Features holds none. ## Where each tool lives Enabled features occupy the scrollable upper sidebar. Unless you rearranged it, they follow the order Writing, Explain, Dictation, Command bar, Shortcuts, Windows, Window switcher, Clipboard, Notes, Scripts, Mr. Usage, System monitor, Stay awake, Menu bar, and App cleaner. Right-click one to pin it to the top, move it up or down, or reset the order; hold Shift and drag a row to put it anywhere, dropping it among the pinned rows to pin it. History, Models, Features, and Settings remain in the lower navigation, so you can always return to configuration even after disabling a tool. Settings retains general, appearance, permissions, history, live configuration/reload, import/export, statistics, and update preferences. - Writing: text rules and in-app Try. Explain: answer rules, notes, and the selection bubble. Dictation: audio rules, Record, and below them Recording: the microphone, muting Mac audio while recording, and a Cancel recording shortcut. - Models → Local models: downloads and installed weights, with Memory (Unload idle models, Unload now) and Storage (the model folder) below the list. Models → Providers: connected local servers and cloud services. Models → Installed tools: Claude Code, supported Codex, and OpenCode text models. - Windows: snapping, the layout picker, sizes, and layout shortcuts. Shortcuts → Application and Other: app and system-action bindings, with a Windows segment for layouts while Windows is off. - Window switcher: its shortcut and any setup issue. Clipboard: the copied text, its search, and the Quick paste shortcut. History: Frog’s own saved writing results, answers, and dictation. - Command bar: its global shortcut and Open button. Mr. Usage: plan limits, token activity, and the menu-bar design. - Notes and Scripts: separate pages backed by the private local document store. - Stay awake: Session and Access controls. App cleaner: installed apps, the review of their leftover files, and Recently moved. - Menu bar: divider-based hiding and reveal controls. System monitor: a live CPU and GPU graph, disk, power, and the settings of its menu-bar item. Settings → Statistics: local recording, rule, and tool totals. ## Organize menu-bar icons Menu bar is off by default. Quit an existing Hidden Bar instance yourself before enabling Frog’s organizer; Frog detects it without changing or terminating it, and starts its organizer once Hidden Bar has quit. Command-drag icons to the left of Frog’s divider, then click the arrow to reveal or collapse that section. Right-click the arrow or click a divider to open its settings. Settings include auto-hide with a configurable delay, start collapsed, optional hover reveal, and an optional hotkey with no default binding. The optional permanently hidden section stays collapsed during ordinary reveal; Reveal all & arrange temporarily opens both sections and pauses auto-hide. Disabling the feature removes Frog’s helpers and shortcut. The organizer uses public menu-bar spacing and requires neither Accessibility nor Screen Recording. macOS 27 and later are unsupported for this feature: Frog installs no organizer helpers there. It has no second-row overflow panel and cannot guarantee access to icons obscured by a notch. Icon positions stay on each Mac. - [Portable menu-bar settings](https://frog.beffa.xyz/docs/configuration/#menu-bar-settings) ## Review local activity in Settings Settings → Statistics shows all-time, 7-day, and 30-day recording counts, microphone time, dictated words, weighted words per minute, rule breakdowns, and tool counts. Collection is enabled by default for these device-local aggregates. Pause it to retain totals without adding new activity, or Reset to clear counters while keeping the collection switch. Statistics stores no transcripts, rule names, queries, provider identities, or individual event logs and makes no network requests. It is separate from optional result history and Mr. Usage. Counters begin with this implementation; old history is not backfilled. The data and collection switch are not included in portable configuration. - [Statistics storage and privacy](https://frog.beffa.xyz/docs/privacy/#local-statistics) ## Disabling stops the feature’s work Return to Features and turn off a tool. Its page and commands disappear, its registered shortcuts are removed, and its owned panels, tasks, polling, or observers stop as applicable. If you are viewing the disabled page, navigation returns to Features. For example, disabling Window switcher removes its keyboard interception and restores the native shortcut; disabling Shortcuts unregisters application and system bindings, and window layouts unless Windows is on; disabling Dictation cancels recording; disabling Scripts cancels its owned process group. Mr. Usage collects while enabled even with its dashboard closed; disabling it or quitting Frog removes its separate menu-bar item and stops collection. Disabling Stay awake first restores sleep for a Frog-owned session. If restoration fails, the app reports the error and keeps the feature enabled so you can resolve access and retry. ## Re-enable without rebuilding your setup Feature disablement preserves saved rules, model choices, shortcut assignments, and toolkit documents. Re-enable the tool in Features to use those settings again. It does not uninstall models or delete notes, the files notes refer to, or saved script text. Temporary data has its own lifetime. Disabling Clipboard clears its memory-only entries; enabling it again starts with new copies. A configuration export includes feature choices and settings, but excludes private toolkit documents, clipboard contents, usage records, history, credentials, and downloaded weights. ## Related guides - [Command bar](https://frog.beffa.xyz/docs/command-bar/) - [System monitor](https://frog.beffa.xyz/docs/system-monitor/) - [Configuration](https://frog.beffa.xyz/docs/configuration/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) - [Getting started](https://frog.beffa.xyz/docs/getting-started/) ## Source documentation - [Frog source and published releases](https://github.com/t1llo/frog) - [Menu-bar organizer behavior and platform limits](https://github.com/t1llo/frog/blob/main/docs/research/hidden-bar-reference.md) - [Local activity statistics](https://github.com/t1llo/frog/blob/main/docs/statistics.md) --- # Frog command bar: search, calculations, and commands on Mac Canonical page: https://frog.beffa.xyz/docs/command-bar/ Updated: 2026-10-29 The optional command bar brings local search and enabled Frog actions into a keyboard panel. Open apps, choose windows, find filenames, jump to a macOS settings pane, paste reusable text, or calculate without setting up an AI model. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Open with Control–Option–Space Change the global binding on Command bar’s page. For notes that paste and clipboard results, Command–Return copies instead of attempting to paste. Other results keep their normal action, so Command–Return is not a universal copy-only mode. App and window results use application icons with compact labels. 1. Enable Command bar in Features. 2. Press Control–Option–Space from the app you are working in, or choose Open on Frog’s Command bar page. 3. Type a name or command and use Up/Down to select a result. 4. Press Return to run it. Escape closes the panel; pressing the opener again also dismisses it. ## Search apps, windows, files, and macOS settings Search is local and does not send queries to an LLM. The panel reuses its app catalog and icons; app results load independently of window discovery. File search matches names, not contents, and depends on Spotlight’s index. Window discovery depends on Accessibility and the windows macOS exposes. Closing the panel cancels its current indexing and file query. Selecting a cloud-backed rule still sends that rule’s input to its configured provider. For writing and window actions, Frog checks that the front application has not changed before delivery. - Applications: find installed apps by name, including Safari’s linked app bundle, and launch or focus them. - Windows: find available titles and app names while Window switcher is enabled; selecting a result activates that individual window. - Files: after at least two characters, Frog asks the local Spotlight index for matching filenames. Selecting a file opens it with macOS. - Frog pages and rules: open enabled tools, Settings, Models, History, or Manage features; run enabled writing, answer, dictation, app, and system rules. Answer rules show Answers in a panel and open the answer next to the selection. - Window layouts: while Windows or Shortcuts is on, search a layout name such as Left half to arrange the original front window. With the layout picker on, type arrange to open it. - Uninstall: while App cleaner is on, type uninstall or remove and an app’s name, such as uninstall example. Choosing a row opens the App cleaner’s review; nothing moves from the command bar. - macOS settings: search the System Settings panes on your Mac by name or a related phrase, such as change desktop for Desktop & Dock and Wallpaper. Each result shows the pane’s own icon, as in the System Settings sidebar. Selecting a result opens that pane; Frog never changes the setting itself. ## Learn from your choices Learn from your choices, under Ranking on the Command bar page, lists the rows you pick for what you type a bit higher. It is off by default. Unused choices fade after a few weeks. Frog keeps the typed text, up to 32 characters, and the rows you picked in ~/Library/Application Support/Frog/command-choices.json, readable only by you. Clipboard rows and windows are never recorded. The file is not exported, synced, or sent anywhere. Forget learned choices… deletes it after a confirmation; turning the switch or the Command bar off deletes it too. ## Calculate and convert units Type an arithmetic expression or conversion and select its Calculation result to copy the answer. Arithmetic supports +, -, *, /, parentheses, ^ for powers, and % for percentages; it runs in a bounded local parser rather than a shell or JavaScript engine. Use four space-separated parts for conversions: number, source unit, to or in, target unit. Both units must be from the same category. Data units distinguish decimal kb/mb/gb from binary kib/mib/gib. These are fixed unit conversions, not currency exchange rates. - 25% * 200 → 50 - (12 + 8) * 3 → 60 - 5 mi to km → 8.04672 km - 32 f to c → 0 c - 2 h in min → 120 min - 1 gib to mib → 1,024 mib ```text Length: mm cm m km in ft yd mi Mass: g kg oz lb Temperature: c f k Time: s min h Volume: ml l gal Data: b kb mb gb kib mib gib ``` ## Use notes, clipboard, and scripts Enable each source in Features to include it. Notes with Paste from command bar turned on fill in date, time, and clipboard variables and attempt a plain-text paste into the captured target; Command–Return copies the filled-in text. Clipboard results preserve available formatting for normal paste, with Command–Return for copying. If the original target changed, the item remains copied for manual pasting. Hidden clipboard entries, such as keys and passwords, are omitted from command-bar previews. Use Clipboard’s dedicated picker to reveal them explicitly. Ordinary clipboard search and note-content matching use bounded previews, so open the full page for broader browsing. Other notes open in Frog. Selecting a saved script explicitly runs it and opens its document; search does not run scripts by itself. Disabling a source removes its actions and dismisses the command bar to invalidate stale results. ## Clean URLs, Base64, and UUIDs These rows are in the command bar whenever it is on; they replaced the Quick actions page in Frog 1.0.39. Clean URL removes query keys beginning with utm_ and the recognized keys fbclid, gclid, dclid, msclkid, mc_cid, mc_eid, igshid, and si; other parameters remain. It does not open the URL or follow redirects. Base64 is an encoding, not encryption. While Shortcuts is on, Lock screen and the other Mac actions are in the command bar too: search lock. Frog’s light and dark appearance is in Settings. - Generate UUID copies a new identifier. - Clean clipboard URL removes recognized tracking parameters from an HTTP or HTTPS URL on your clipboard and copies the result. - Base64 encode clipboard copies the clipboard’s text as Base64. Text an app marked as sensitive, such as a password, is not encoded. - Base64 decode clipboard copies the decoded text when the clipboard holds Base64 that decodes to UTF-8 text. ```text Input: https://example.com/article?utm_source=newsletter&id=42 Result: https://example.com/article?id=42 ``` ## Emoji Search words such as emoji frog, coffee, heart, or rocket to copy an emoji from Frog’s small built-in collection. This is a curated set rather than the full macOS character catalog. ## Related guides - [Choose features](https://frog.beffa.xyz/docs/features/) - [Clipboard](https://frog.beffa.xyz/docs/clipboard/) - [Notes](https://frog.beffa.xyz/docs/notes/) - [Saved scripts](https://frog.beffa.xyz/docs/scripts/) - [App cleaner](https://frog.beffa.xyz/docs/app-cleaner/) ## Source documentation - [Frog source and published releases](https://github.com/t1llo/frog) --- # Writing rules: proofread and rewrite text on Mac | Frog Canonical page: https://frog.beffa.xyz/docs/writing-rules/ Updated: 2026-10-16 Frog’s writing rules act on text where you are already writing. Open Writing to manage instructions, model choices, and optional global shortcuts for proofreading, rewriting, or translation. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ![Trying a Frog writing rule: a draft sentence and its corrected result](https://frog.beffa.xyz/screenshots/frog-rules.png) Try a rule in Frog before using its shortcut in another app. ## Create a rule for a recurring task Models are selected per rule. You can use a small local model for spelling corrections and a different model for another task. Adding a model does not silently change configured rules. Enabled writing rules also appear in the optional command bar. Disabling Writing in Features removes its commands and shortcuts and cancels its active processing. Rule definitions and model choices remain for when you enable it again. 1. Enable Writing in Features if needed, then open Writing and choose New rule or edit an existing rule. 2. Give it a useful name and describe the change you want in the instructions. 3. Choose a downloaded local text model or a configured provider model. Manage these in Models → Local models or Models → Providers. 4. Record a keyboard shortcut and enable the rule. Use Try to enter sample text and Run it inside Frog. ## Examples of writing instructions Write the target language directly in a translation rule’s instructions. These are example prompts, not guaranteed outputs: results depend on the text and the chosen model. - Proofread: Fix spelling and grammar. Keep my tone and meaning. - Shorten: Make this more concise while preserving the important details. - Polish an email: Make this email clear and friendly without adding new information. - Translate: Translate this text into German. Preserve names and formatting where possible. ## Select text, run the shortcut, and review the result Select text in a supported editable field and invoke the rule. Frog processes that selection, then checks the original target before inserting the result. If focus, selection, or the field has changed, automatic replacement may be skipped. The processed result remains available on the clipboard. Accessibility support varies between apps and fields. Read-only content cannot be rewritten in place. Use the clipboard result when a field cannot accept automatic replacement. To ask about text without changing it, use an answer rule on the Explain page. ## Where is the text processed? Downloaded internal text models use local MLX inference on Apple silicon. An Ollama or LM Studio connection can also process text on your Mac when its endpoint is local. A cloud-backed rule sends the selected text and instructions to that cloud service. Frog does not continuously record your typing. It works with the selection you invoke a rule on. Optional result history is stored locally and is off by default. ## Related guides - [Explain](https://frog.beffa.xyz/docs/explain/) - [Local models](https://frog.beffa.xyz/docs/local-models/) - [Model providers](https://frog.beffa.xyz/docs/providers/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Frog model selection documentation](https://github.com/t1llo/frog/blob/main/docs/providers.md) - [Text replacement and privacy details](https://github.com/t1llo/frog/blob/main/docs/privacy.md) --- # Explain: ask about selected text on Mac | Frog Canonical page: https://frog.beffa.xyz/docs/explain/ Updated: 2026-10-16 Explain answers questions about text you select in another app. The answer appears in a panel next to the selection, and nothing in your app is replaced. Explain is off by default; turn it on in Features. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Turn on Explain and run it Explain uses answer rules. Like writing rules, each has its own instructions, model, and shortcut, but its result opens in a panel instead of replacing your text. Answer rules have no Try, because an answer needs a selection. Turning Explain off removes its shortcuts, bubble, and panel; the rules and settings stay. 1. Turn on Explain in Features. Explain appears in the sidebar with one answer rule, also named Explain, that has no shortcut yet. 2. Open Explain, check the rule’s model, and record a shortcut. Choose New answer rule for other questions, such as a definition or a translation. Each answer rule uses its own model. 3. Select text in another app and press the shortcut. You can also run an answer rule from the command bar or from the selection bubble. ## Read, follow up, and save the answer The answer panel opens next to the selection. Explain’s own instructions ask for one to three plain sentences; edit the rule’s instructions for longer answers. With History on, answers also appear in History under their own Answers filter. - One line at the top shows the rule and its model, with Keep open (the pin) and Close. Escape closes the panel too. - Ask a follow-up continues in the same panel, with the earlier questions and answers. - The icons beside the follow-up field are Stop (⌘.) while an answer is still running, Copy (⌘↩), and Save to note (⌘S) while Save answers to notes is on. - If an answer fails or you stop it, Retry runs it again; after a failure, Edit rule opens the rule’s editor. ## Surrounding text and notes Include surrounding text, on by default, sends the sentence or paragraph around the selection, up to 1,000 characters, so the answer fits the context. Turn it off to send the selection only. Save answers to notes adds Save to note to the panel and to answers in History. Choose a Folder, such as an Obsidian vault, then choose One note per answer or Add to one note under Save as. Add to one note writes to the File you name inside the folder, by default Daily/YYYY-MM-DD.md, where YYYY, MM, and DD become today’s date. Open the note after saving opens it in Obsidian when the folder is inside a vault, otherwise in your Markdown app. ## Show a bubble when you select text With Show a bubble when you select text on, a small bubble appears after you select text in another app. It offers Explain and your other answer rules, and in text fields also your Writing rules. Its other settings are under Options. Also after a double-click and Also after selecting with the keyboard, both on, show it after a double-click or a selection with Shift and the arrow keys. Longer selections than Longest selection, 4,000 characters by default, show no bubble. Chrome, Arc, Helium, Slack, Obsidian and other Chromium and Electron apps keep their text hidden from Accessibility. With Chrome and Electron apps on, the default, the bubble still appears there after you select with the mouse, at the pointer, and offers your answer rules; the text is copied only when you pick one, the way Explain’s shortcut copies it, with the clipboard restored. Frog does not switch these apps to the mode a screen reader uses, so they stay as fast as without Frog. VS Code and the editors built on it, such as Cursor and Windsurf, show no bubble. Explain’s shortcut works in every app either way. Show in selection bubble, a switch in each rule’s editor, decides whether the bubble offers that rule; Writing rules appear only in text fields. A rule left out says Not in the bubble in its row. Explain comes first; past four rules, the rest open from the arrow at the end of the bubble, grouped into Answer and Replace selection. Never show in lists apps where the bubble never appears, and Choose an App… adds one. 1Password, Bitwarden, Keychain Access, and Passwords are on it from the start. The bubble never shows in password fields, in games, or while secure input is on. Frog reads the selection through Accessibility and never copies it. ## What Explain sends and saves When you run an answer rule, Frog sends its model the selected text, the rule’s instructions, the surrounding text when that setting is on, the app’s name, the reply language (your Mac’s first preferred language), and earlier questions and answers in the same panel. The page or document address is never sent. A local model keeps all of this on your Mac; a cloud model receives it. While the panel is open, Frog watches keys pressed in other apps for the Escape key only and reads no characters. Notes are written only when you press Save to note. They hold the selection, the answer and its follow-ups, the app’s name, and the model; a note per answer also holds the page or document address. The surrounding text is not written to notes. ## Related guides - [Writing rules](https://frog.beffa.xyz/docs/writing-rules/) - [Local models](https://frog.beffa.xyz/docs/local-models/) - [Model providers](https://frog.beffa.xyz/docs/providers/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Explain, selection bubble, and notes privacy details](https://github.com/t1llo/frog/blob/main/docs/privacy.md) - [Explain configuration keys](https://github.com/t1llo/frog/blob/main/docs/configuration.md) --- # Local dictation and speech-to-text on Mac | Frog Canonical page: https://frog.beffa.xyz/docs/dictation/ Updated: 2026-10-26 Open Dictation to turn microphone recordings into text through audio rules. Choose a speech model, a recording shortcut, and output behavior. Transcription can run locally on Apple silicon, with optional cleanup by a separate text model. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Set up an audio rule The built-in Dictate shortcut is Option–Space, and shortcuts are editable. Record on the Dictation page starts a recording directly; the recording controls let you stop it. Escape cancels. Below the rules, Recording chooses the microphone, can mute Mac audio while recording, and takes an optional Cancel recording shortcut besides Escape. Disabling Dictation in Features cancels active dictation and unregisters its rules’ shortcuts while preserving their settings. 1. Enable Dictation in Features if needed. Download a speech model in Models → Local models or add a compatible speech-to-text model in Models → Providers. 2. Open Dictation, add or edit an audio rule, and select its speech model. Set a transcription language where supported. 3. Choose hold-to-record or press-to-toggle recording and record your preferred shortcut. 4. Choose clipboard output or copy-and-paste output. Enable transcript cleanup only if you want a text model to rewrite the transcription. ## Local speech models and languages Frog’s internal catalog includes Whisper variants using WhisperKit and Core ML, and Parakeet variants using FluidAudio and Core ML. Downloadable inference requires Apple silicon. Model weights are downloaded explicitly and are not bundled with the app. Whisper multilingual models can detect language automatically or use a rule’s language hint. Parakeet v3 supports its own set of 25 European languages with automatic detection; Parakeet v2 is English-only. The selected model determines the language options and whether partial transcription is available. ## Keep your words or clean up the transcript Without cleanup, the speech model’s transcript is the output. With cleanup, Frog applies the rule’s instructions using its selected text model. For example, a cleanup instruction can remove filler words and fix punctuation while preserving your meaning. Cleanup adds a second processing step. A local speech model plus a local text model keeps both steps on your Mac. Cloud text cleanup sends the transcript and instructions to that provider. If cleanup fails, Frog preserves the original transcript on the clipboard. Copy-and-paste output attempts insertion into the currently focused field after transcription, so you can change input fields while recording. Password fields are excluded when identified by Accessibility. The clipboard remains useful if the destination app cannot accept automatic insertion. ## When does Frog record? Recording starts when you invoke an audio rule or Record and stops automatically after ten minutes. Local transcription keeps microphone audio in process memory and discards it after completion or cancellation. If transcription fails in a way a second attempt can fix, the recording stays in memory until you retry or discard it in the popup. Choosing an external speech model sends the recording to that provider. Audio files are not added to Frog’s history. Saved result history is a separate opt-in setting in Settings → History. Clipboard collection is enabled independently in Features, and copied text appears on the Clipboard page. ## Related guides - [Local models](https://frog.beffa.xyz/docs/local-models/) - [Model providers](https://frog.beffa.xyz/docs/providers/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Audio rule settings](https://github.com/t1llo/frog/blob/main/docs/providers.md) - [Speech model capabilities](https://github.com/t1llo/frog/blob/main/docs/local-model-sources.md) --- # Offline AI models for writing and dictation | Frog for Mac Canonical page: https://frog.beffa.xyz/docs/local-models/ Updated: 2026-10-26 Models → Local models is the home for Frog’s downloaded speech and text models, with their memory and storage settings below the list. With an Apple silicon Mac and the required weights installed, writing, transcription, and local transcript cleanup can work offline. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ![Frog’s local speech models: one downloaded recommended model and one available to download](https://frog.beffa.xyz/screenshots/frog-internal-models.png) Download a model once, then select it in the rules that need it. ## What is required for offline use? Internet access is needed to download model files initially. After installation, local inference does not need a cloud API key or a per-request API service. Downloading an update or an additional model still needs a connection. - macOS 14 or later and Apple silicon for built-in inference. - An explicit download of each speech or text model you intend to use. - Enough storage and memory for the models you select. Each model lists its real download size, which does not describe total memory use. - A rule that selects a local model for every processing step, including optional dictation cleanup. ## Speech and text use different models Speech models turn microphone recordings into text. The catalog includes Whisper models through WhisperKit/Core ML and Parakeet models through FluidAudio/Core ML. Text models rewrite writing or clean up a transcript using MLX. The text catalog includes Qwen3, Llama 3.2, and Gemma 3 variants in compatible MLX formats. The setup assistant’s recommended local pair is Whisper Large v3 Turbo for speech and Qwen3 1.7B (4-bit) for text. An older Turbo conversion you installed or selected before stays available as Whisper Large v3 Turbo · earlier build. The model information panel identifies the source, runtime, and available license details. ## Download and use an internal model Downloaded files are stored under ~/Library/Application Support/Frog/Models/ by default. Storage, below the model list, shows the folder and how much the downloaded models use, with Choose folder…, Use default, and Show in Finder. Model weights are device-local and are not included in JSON configuration exports. Models stays in the lower sidebar even when Writing or Dictation is disabled. Disabling a feature does not delete its downloaded weights. Memory lists the models in memory and offers Unload now when they are not busy. 1. Open Models and choose Local models. Providers is the separate tab for connected services. 2. Find a speech or text model and select Download. Frog downloads the weights only after this action. While they arrive, the row shows the bytes so far, the speed and about how long is left, and says when the download has stalled. 3. Open Writing or Dictation, edit the rule that should use the model, and select it. 4. Run the rule. Models load on demand and unload after the delay set in Unload idle models, under Memory below the model list, or sooner when macOS runs short of memory. ## Disk space, model folders, and repairs Before a download starts, Frog checks that the disk of the model folder has room for the model and a small spare, counting what the downloads already running still have to fetch. When it does not fit, Frog refuses the download and says how much space the model needs and how much is free. A resumed download needs room only for what it has not fetched yet. Each downloaded row shows the space its folder takes, and the Downloaded list adds them up. Frog does not move downloads. When you choose another folder while models are downloaded, it asks first: it says how many models stay in the current folder and the space they use, and that it will list only the models in the new folder. Choose the earlier folder again to use them. A text or Parakeet download counts as finished only once the files its runtime needs are there; otherwise the row stays partly downloaded and names what is missing. Check files in a downloaded model’s menu finds missing or damaged files and offers Repair, which fetches them again into the same folder. If a repair fails or is cancelled, the row still names what the model lacks and offers Repair. When a downloaded model does not load, its error suggests Check files. ## Can I add another model? Frog supports adding compatible public Hugging Face model sources. Checking a source fetches repository metadata, including the size of each file, and, for text models, configuration information; downloading the weights is a separate action. The added model shows its download size. For a source added with an earlier version of Frog, check it again and choose Show model to save its size. Custom text models need supported MLX formats and architectures. Custom Whisper models need complete WhisperKit Core ML bundles. Raw PyTorch, GGUF, and arbitrary NeMo files are not interchangeable with those formats. Use the source documentation for exact supported formats and model provenance. ## Related guides - [Dictation](https://frog.beffa.xyz/docs/dictation/) - [Writing rules](https://frog.beffa.xyz/docs/writing-rules/) - [Model providers](https://frog.beffa.xyz/docs/providers/) ## Source documentation - [Model catalog, formats, and provenance](https://github.com/t1llo/frog/blob/main/docs/local-model-sources.md) - [Internal model setup](https://github.com/t1llo/frog/blob/main/docs/providers.md) --- # Connect Ollama, LM Studio, or cloud AI models | Frog Canonical page: https://frog.beffa.xyz/docs/providers/ Updated: 2026-10-10 Models → Providers connects Frog to local servers, cloud APIs, or compatible endpoints. Models → Installed tools uses supported coding CLIs with their existing login. Downloaded models that run inside Frog live under Models → Local models. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Add a provider connection Use model IDs your account or server supports. Changing a display name does not change the API ID. API keys are stored in macOS Keychain rather than portable configuration files. Testing a text connection sends a short test message. Provider connections are separate from Mr. Usage logins. The usage dashboard reads credentials owned by your coding tools; adding a writing provider here does not configure a usage account. 1. Open Models → Providers and add a connection. 2. Name the connection, choose the service, and enter its endpoint and credentials where required. 3. Add the models available to that service. Each model has an API ID, a display name, and a text or speech-to-text category. 4. Test and save the connection, then select one of its models in Writing or Dictation. ## Use Ollama on your Mac Frog connects to the existing Ollama server; it does not install or manage the server. A localhost endpoint processes requests on your Mac. A remote Ollama endpoint processes them on the machine hosting that endpoint. 1. Install and start Ollama, then download a compatible text model through Ollama. 2. Add an Ollama connection in Frog. The usual local endpoint is http://localhost:11434. 3. Choose Find installed models, select the models you want, test the connection, and save. ## Use LM Studio on your Mac Model discovery asks the configured server for its model list. It does not send your writing or microphone recordings. 1. Install LM Studio, download a model, and start its local server in the Developer section. 2. Add an LM Studio connection in Frog. The usual local endpoint is http://localhost:1234/v1. 3. Find installed models, test the connection, and save. Supply an API token if your server requires one. ## Connect a cloud service Frog supports OpenAI, Anthropic Claude, Google Gemini, and compatible API endpoints. Cloud services use their own credentials, model availability, pricing, and data policies. When you run a cloud-backed writing rule, the selected text and instructions are sent to that service. External speech-to-text is available through supported OpenAI transcription, Gemini audio input, and compatible transcription endpoints. Selecting an external speech model sends the recording for transcription. Not every text provider offers speech-to-text. ## Use an installed coding tool’s text models Frog invokes the supported CLI in the background for text transformations, with restricted tool access and cancellation. It does not automate a desktop chat window, install the tool, or sign you in. Codex support is limited to verified 0.159.x interfaces; other minor versions remain unsupported. A detected login is not a guarantee that every model is available to the account. The portable tool-default model ID is @default; Frog omits the CLI model argument for that choice. Executable paths, login state, and tokens stay out of configuration. The CLI owns authentication and any credential refresh; Frog does not copy its credentials into Frog’s Keychain. Requests still use the selected tool’s provider and account policies, so an installed CLI does not imply offline inference. OpenCode retains its own CLI session history even when Frog’s result history is off. Frog’s temporary request files are removed after use. Isolated tool invocation does not import custom provider aliases or project customization; use an available model or the tool default. 1. Install and sign in to Claude Code, Codex, or OpenCode through that tool’s own setup. 2. Open Models → Installed tools. Frog shows installation, login, and supported-interface status separately. 3. Choose an available text model or the tool default and select Use model. Frog creates or updates the connection without an endpoint or Frog API-key form. 4. Select that model in a writing or translation rule, or as the text model for dictation cleanup. ## Choose a model for each rule Each rule stores its own model selection; there are no global model defaults that reroute configured rules. You can mix local and cloud-backed rules. Deleting a provider connection clears affected rule selections rather than silently switching them to another provider. ## Related guides - [Local models](https://frog.beffa.xyz/docs/local-models/) - [Writing rules](https://frog.beffa.xyz/docs/writing-rules/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Provider endpoints and supported model categories](https://github.com/t1llo/frog/blob/main/docs/providers.md) - [Installed-tool integration and support boundaries](https://github.com/t1llo/frog/blob/main/docs/local-tool-providers.md) --- # Keyboard shortcuts to open Mac apps | Frog Canonical page: https://frog.beffa.xyz/docs/app-shortcuts/ Updated: 2026-10-16 Shortcuts gives Mac applications and system actions configurable keyboard bindings. Launch an app or bring it forward without a language model. Window layouts are on the Windows page while that feature is on, otherwise under Shortcuts → Windows. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Assign an app to a shortcut Other contains system actions. The Windows segment holds layout bindings while the Windows feature is off; while it is on, Shortcuts shows only Application and Other. Disabling Shortcuts removes its registered bindings and preserves assignments for later; window layouts keep working while Windows is on. The optional command bar also searches installed applications by name, without assigning a dedicated shortcut to each app. Its default shortcut is Control–Option–Space. 1. Enable Shortcuts in Features, then open Shortcuts → Application and find an installed app. 2. Record the keyboard combination you want to use. Recording a binding enables the application shortcut. 3. Press the shortcut from another app. Frog opens the target application or brings it forward. ## 28 native actions under Other Record a binding to enable an action. Settings actions open the corresponding macOS pane; they do not toggle radios or promise hardware controls. Screenshot controls opens the native Screenshot app. Current-app commands and Lock Screen use enabled Accessibility menu commands, so availability depends on the app and permission. Unsupported commands report an error rather than sending synthetic shortcuts. - Finder folders: Home, Desktop, Documents, Downloads, Applications, Utilities, and Library. - Settings destinations: System Settings, Wi-Fi, Bluetooth, Display, Sound, Keyboard, Trackpad, Accessibility, Privacy & Security, Notification, and Storage settings. - Mac controls: Lock Screen, Screenshot controls, and Hide current app. - Current-app commands: Undo, Redo, Cut, Copy, Paste, Select all, and Find in current app. ## App shortcuts, window positioning, and window switching An app shortcut targets a known application: for example, bringing Notes forward whenever you press your chosen binding. A window-positioning shortcut acts on the focused window, such as moving it to the left half of the display. The Command–Tab switcher chooses among individual open windows, including multiple windows from the same app. Writing and audio rules are different again. They process selected text or a recording using a model. Launching an application or positioning a window does not send a writing prompt or microphone recording to a provider. ## Move your shortcut setup between Macs Application shortcut configuration is included in Frog’s JSON import and export. Application targets use an application path and bundle identifier. The corresponding application still needs to be installed on the destination Mac, and device-specific permissions need to be configured there. Record keyboard bindings in Frog’s interface rather than manually calculating key codes in JSON. You can keep an exported setup with the rest of your configuration files and import it through Settings. ## Related guides - [Command bar](https://frog.beffa.xyz/docs/command-bar/) - [Windows](https://frog.beffa.xyz/docs/window-management/) - [Configuration](https://frog.beffa.xyz/docs/configuration/) ## Source documentation - [Application actions and shortcut configuration](https://github.com/t1llo/frog/blob/main/docs/configuration.md) --- # Window management on Mac: snap, zones, and layouts | Frog Canonical page: https://frog.beffa.xyz/docs/window-management/ Updated: 2026-10-26 Windows gives window management its own page in Frog. Drag windows to screen edges, hold Shift for zones, open the layout picker, or give layouts shortcuts. Windows is off by default and runs locally without an AI model. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Choose Snap once to set it up Nothing moves by itself: Frog moves a window only when you drag it, press a shortcut, or pick a layout. 1. Turn on Windows in Features and open the Windows page. If it asks for Accessibility, choose Allow Accessibility first. 2. The card How do you want to arrange windows? offers Snap. Keep Add suggested shortcuts (⌃⌥ with arrows and letters) ticked to give layouts shortcuts where they are free. 3. Choose Snap. It turns on Drag to screen edges, Restore size when dragged away, Show zones while holding Shift, and Layout picker. Undo puts the Windows settings back. 4. Or choose Set up myself to change nothing and use the settings on the page. ## Drag a window to an edge or corner Switch on Drag to screen edges under Snap, then drag a window by its title bar and let go at an edge of the screen. A tinted area shows where it will go; press Escape before letting go to keep it where macOS drops it. With Restore size when dragged away on, a window you drag out again gets back its earlier size. Where it lands depends on the edge: - Left or right edge: the window fills the left or right half. - Top edge: the window fills the display (Maximize on display). - A corner: the window fills that quarter. - Bottom edge: the window fills the third under the pointer. ## Hold Shift for zones With Show zones while holding Shift on, hold Shift while dragging a window and zones cover the display under the pointer. Let go over one to fill it. Choose Halves, Thirds, Quarters, or Main and side under Zones; Thirds is the default. On macOS 15 and later, macOS can tile windows dragged to an edge by itself. While its Drag windows to screen edges to tile setting is on, Frog’s edges pause and Shift zones still work. While Drag windows to menu bar to fill screen is on, which it is by default, Frog’s top edge and top corners pause too. Open Desktop & Dock on the page goes to these settings; Frog never changes them. ## Pick a layout or hold the cheat sheet Switch on Layout picker under Snap and give it a shortcut; the suggested one is ⌃⌥W. Open it with the shortcut, with Arrange window… in the Frog menu, or by typing arrange in the command bar. It shows every layout as a small picture. Use the arrow keys or type a name such as third, then press Return. Record a shortcut under Cheat sheet → Show window shortcuts while holding; the suggested one is ⌃⌥/. While you hold it, a panel lists every window shortcut you have. Release it to close the panel. ## Gaps, cycling sizes, and Stage Manager These settings apply while Windows is on. A window dragged to an edge gets the same gap, thirds, and room for Stage Manager as with a shortcut. - Gap between windows: 0 to 40 points around the screen edge and between windows. - Cycle sizes when pressed again: a half pressed again takes two thirds, then one third. Off by default. - Thirds run top to bottom on tall displays: for a display that is taller than wide. On by default. - Leave room for Stage Manager: keeps 190 points free for its strip while Stage Manager is on. On by default. ## Which 23 layouts are available? Under Layout shortcuts, click a row’s shortcut field and press a key combination; recording it switches the layout on. Use suggested shortcuts gives every free layout the ⌃⌥ set: arrows for halves, U, I, J, and K for quarters, D, F, and G for thirds, E and T for two-thirds, Return to maximize, C to center, and Delete to restore. ⌃⌥⌘ with an arrow moves a window to the next or previous display. A combination Frog already uses elsewhere is skipped. Layout shortcuts run while Windows or Shortcuts is on. While Windows is on, the layouts are on its page; switch it off and they are under Shortcuts → Windows again, with the same shortcuts. The command bar finds layouts by name, such as Left half. When a window moves to another display, Frog keeps it within that display. - Left, right, top, and bottom halves of the display. - Top-left, top-right, bottom-left, and bottom-right quarters. - Left, center, and right thirds; left and right two-thirds. - Centered sizes at 50%, 70%, or 90% of the display’s available width and height. - Maximize on the current display or minimize the window. - Center the window while preserving its size where it fits. - Restore the window’s previous size and position. - Move the window to the next or previous display. - Toggle macOS full-screen mode. ## Restore the previous window position Restore previous size returns the window to its size and position from before Frog moved it: after several layouts in a row, to where it was before the first, and after a drag to an edge, to where the drag began. A window dragged out of its layout and dropped elsewhere has nothing to return to. If the original display has been disconnected, Frog keeps the restored window on an available display. The app keeps recent restore frames locally. This is window geometry, not a screenshot or writing history. ## Accessibility and what Frog reads Frog uses macOS Accessibility to move and resize windows; until access is granted, the page shows Allow Accessibility. It does not record your screen. An app can restrict moving or resizing its windows, and full-screen windows are not snapped. While drag to screen edges or Shift zones are on, Frog watches mouse-button and drag events to notice a window drag, without recording them. Once a drag starts, it reads the position and size of the window under the pointer a few times at most and reads no window titles. Window switcher is a separate feature that chooses among open windows, with its own Window switcher page; turn it on in Features. ## Related guides - [Window switching](https://frog.beffa.xyz/docs/window-switching/) - [App shortcuts](https://frog.beffa.xyz/docs/app-shortcuts/) - [Command bar](https://frog.beffa.xyz/docs/command-bar/) - [Configuration](https://frog.beffa.xyz/docs/configuration/) ## Source documentation - [Windows guide in the app repository](https://github.com/t1llo/frog/blob/main/docs/windows.md) - [Supported window actions](https://github.com/t1llo/frog/blob/main/native/FrogCore/WindowAction.swift) - [Native window positioning implementation](https://github.com/t1llo/frog/blob/main/native/FrogApp/Platform/WindowManager.swift) --- # Command–Tab switching between Mac windows | Frog Canonical page: https://frog.beffa.xyz/docs/window-switching/ Updated: 2026-10-26 Window switcher is a Command–Tab replacement that switches between individual windows, including multiple windows of the same app. Turn it on in Features; its shortcut and status are on its own Window switcher page. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ![Frog’s window switcher listing four example windows with their app names](https://frog.beffa.xyz/screenshots/frog-window-switcher.png) Window titles and app names help distinguish multiple windows from the same app. ## Find a window from the keyboard The switcher uses recent-window ordering and shows titles with app names. Availability and activation across apps and Spaces depend on the Accessibility information macOS exposes. Disable Window switcher in Features to restore the native shortcut and stop Frog’s window work. Layout shortcuts belong to Windows or Shortcuts and keep working. The command bar includes available window results only while Window switcher is enabled. Command–Tab is the default. Record a different shortcut beside Switch windows on the Window switcher page; hold its modifiers to keep switching, release them to focus the selection, and add Shift to move backward. 1. Enable Window switcher in Features and grant Accessibility access. Its page reports any setup issue. 2. Hold Command and press Tab to open the switcher and cycle through windows. Add Shift to reverse direction. 3. Type to filter by window title or use arrow keys to navigate. Rows are also clickable, and moving the pointer across the list selects the row under it; a pointer that only rests where the list opens changes nothing. 4. Release Command or press Return to choose the selected window. Escape cancels. ## Why does the switcher need Accessibility? Frog uses macOS Accessibility APIs to list window titles, observe the recently focused window, and activate your choice. It does not capture window screenshots and does not need Screen Recording permission. A keyboard event tap recognizes the switcher shortcut and its navigation keys. Ordinary typing is passed through and is not recorded. Disabling the switcher removes that event tap. ## Window switching runs locally without an AI model Window titles, application identities, and recent-window order stay in process memory. They are not sent to an AI provider or written into Frog’s result history or exported configuration. You do not need to download a speech or text model to switch windows. Application shortcuts complement the switcher: a dedicated shortcut opens or focuses a chosen app, while the switcher lets you choose among its available windows. ## If a window does not appear Check that the switcher is enabled and Frog has Accessibility permission. Some applications expose limited window information, and macOS Spaces behavior can affect what can be activated. The feature depends on those system capabilities rather than analyzing screenshots to discover hidden windows. While another app is asking for a password, also in a window left in the background, macOS gives the keyboard to that app only, and Command–Tab falls back to the macOS app switcher. Frog shows a short notice naming the app and marks the switcher as paused on its page; enter the password or close that window to continue. ## Related guides - [App shortcuts](https://frog.beffa.xyz/docs/app-shortcuts/) - [Windows](https://frog.beffa.xyz/docs/window-management/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Window-switcher implementation and privacy notes](https://github.com/t1llo/frog/blob/main/docs/privacy.md) - [Shortcut configuration](https://github.com/t1llo/frog/blob/main/docs/configuration.md) --- # Frog clipboard history: search and paste 100 recent text items Canonical page: https://frog.beffa.xyz/docs/clipboard/ Updated: 2026-10-29 Clipboard keeps the last 100 copied text items in memory while enabled. Browse them on the Clipboard page or use the global picker to return an earlier copy to the app you were using. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Enable Clipboard and collect new copies Clipboard checks for new text approximately twice a second. It retains at most 100 items, including writing and dictation results, with available bounded RTF/HTML formatting. Non-text and multiple-item payloads are not retained. Text over 512 KiB and formatting over 1 MiB per format are excluded. Copied text appears only on the Clipboard page; History shows Frog’s own activity. Enabling saved result history does not write these copies to disk. 1. Turn on Clipboard in Features. It is off by default. 2. Copy text in another app. Frog begins collecting new copies rather than importing the clipboard that existed before enablement. 3. Open the Clipboard page in the sidebar to search the copied text, reveal details, or copy an item. 4. Record a different Quick paste shortcut in the Clipboard page’s header if Shift–Command–V conflicts with your workflow. ## Paste with the keyboard picker Automatic paste checks the original app, window, field, and insertion range. If that target changed or is not suitable, the chosen text stays copied for manual paste. While Clipboard is enabled, Shift–Command–V opens Frog’s picker instead of that combination’s native action. Command–C/X/V and Command–Option–Shift–V remain with the focused app. Disabling Clipboard unregisters its shortcut. 1. Focus the destination field, then press Shift–Command–V. 2. Type to search or use arrow keys to select an item; the list can reach all 100 entries. 3. Press Return or double-click an item for normal paste with available formatting, or Shift–Return for plain-text paste. 4. Use Copy or Command–C to copy without inserting. Escape dismisses the picker. ## Keys and passwords stay hidden Ordinary copies are visible and searchable by default. Text that looks like an API key, token, private key, password or credentials starts hidden, and so does text its source app marks concealed or transient. A hidden item shows as dots and names its kind, such as API key or Password, and still copies and pastes whole. In the picker, select it and press Space or click its eye; on the Clipboard page, click it. Hidden contents do not match text searches until revealed. Closing the picker or leaving the Clipboard page hides the text again. The command bar omits hidden entries. Copying or pasting a hidden item preserves a concealed marker even for plain-text paste, and keeps it on this Mac rather than offering it to your other devices. Frog recognizes keys and passwords on your Mac, from the key formats of common services, assignments such as API_KEY= or password:, and single words that read like a password or a random key. It reads at most the first 64 KB of a copy and sends nothing anywhere. Recognition is not perfect: an unusual password can still appear as ordinary text, and hiding a preview does not encrypt its contents. Settings → History → Hide history text is a separate display preference that can mask previews and details. ## Clear copies and stop collection Delete individual entries on the Clipboard page, or choose Clear clipboard in its ⋯ menu. The picker also has Clear. Deleting or clearing entries invalidates pending delivery; disabling Clipboard or quitting Frog forgets all retained entries and stops collection. Clipboard contents are never configuration-export payloads, saved history files, or provider inputs by this feature. Clearing Frog’s retained history is separate from the current macOS clipboard and from any other clipboard manager’s storage. Completed AI results can still be copied by Writing or Dictation when Clipboard is off. ## Related guides - [Choose features](https://frog.beffa.xyz/docs/features/) - [Command bar](https://frog.beffa.xyz/docs/command-bar/) - [Notes](https://frog.beffa.xyz/docs/notes/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [App clipboard privacy details](https://github.com/t1llo/frog/blob/main/docs/privacy.md) --- # Frog Notes: Markdown notes, and text to paste from the command bar Canonical page: https://frog.beffa.xyz/docs/notes/ Updated: 2026-10-26 Notes keeps Markdown notes privately on this Mac, in a store outside portable configuration exports. A note can also paste from the command bar, which is what Snippets did before Frog 1.0.39. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Write and preview a note Export saves a note’s text as a .md file. If Command bar is enabled, note titles and a bounded content preview are searchable there, and selecting a result opens the note. These are local notes with no Frog cloud-sync service. 1. Enable Notes in Features and open its sidebar page. 2. Choose New, give the note a title, and write in the editor. Changes save automatically; a save problem appears inline. 3. Use Preview to render Markdown text, then return to editing with the same toggle. 4. Search titles and content on the Notes page. Copy puts the text on the clipboard; the overflow menu offers Export, Share text, and Delete item. ## Paste a note from the command bar Date and time use the Mac’s locale. Filling in is one pass: clipboard text that contains variable-like strings is not expanded again. A concealed clipboard marker is preserved when a note includes {{clipboard}}. Frog does not expand abbreviations as you type in other apps. Notes without the switch open in Frog when you choose them in the command bar. Export and sharing use the text as written, so use Copy or the command bar when you want the variables filled in. 1. Open a note and turn on Paste from command bar, next to its Edit and Preview toggle. The note gets a small mark in the list. 2. Write the text you reuse and optionally include {{date}}, {{time}}, or {{clipboard}}. 3. With Command bar enabled, search the note’s title and press Return to paste it into the app you were in, or Command–Return to copy it instead. 4. Copy on the Notes page fills in the variables the same way. ```text Update for {{date}} at {{time}} {{clipboard}} Thanks! ``` ## Snippets and shelf items from earlier versions Frog 1.0.39 folded Snippets and Shelf into Notes. Your snippets became notes with Paste from command bar turned on, and each shelf item became a note that keeps its text and its files. Notes is turned on for you if you used either feature. A note that came from the shelf lists its files with Open, Reveal, and Share, and you can drag a file to another app. Frog keeps references, not copies: moving or deleting the original can make a reference unavailable, and deleting the note leaves the file untouched. ## Private persistence and document limits Notes and script text share ~/.config/frog/Toolkit/toolkit-documents.json. The local directory and file use user-only permissions; this JSON is not an encrypted vault. None of these documents is included when exporting config.json. The store permits up to 1,000 notes and scripts in total, at most 1 MB of text and 100 file references per item, and a 16 MB total file. A failed save is shown in the page rather than silently treated as success. Turning Notes off removes its page and command bar results while keeping your notes. Turning it on again restores them. Explicit export or sharing creates a copy outside this private store under your control. ## Related guides - [Command bar](https://frog.beffa.xyz/docs/command-bar/) - [Clipboard](https://frog.beffa.xyz/docs/clipboard/) - [Saved scripts](https://frog.beffa.xyz/docs/scripts/) - [Configuration](https://frog.beffa.xyz/docs/configuration/) ## Source documentation - [Frog source and published releases](https://github.com/t1llo/frog) - [App local-data documentation](https://github.com/t1llo/frog/blob/main/docs/privacy.md) --- # Save and run local shell scripts in Frog Canonical page: https://frog.beffa.xyz/docs/scripts/ Updated: 2026-10-26 Scripts keeps small local shell tasks ready to run from their page or the command bar. Saving or searching a script does not execute it; Run or selecting its command-bar result is the execution action. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Create and run a script With Command bar enabled, selecting a saved script opens its document and runs it. The page disables Run while a script is active. Results are associated with the originating script rather than displayed on whichever document you happen to open. 1. Enable Scripts in Features and open Scripts. 2. Choose New, give the script a title, and enter its shell commands. Changes save to the private document store. 3. Press Run. Frog shows Running and the output as it arrives, then the exit status. 4. Use Copy output to copy a completed result, or Stop to cancel active execution. ```sh printf 'Current folder: ' pwd printf '\nCurrent date: ' date '+%Y-%m-%d' ``` ## Execution environment and limits The process inherits Frog’s environment, with the Homebrew folders /opt/homebrew/bin and /usr/local/bin added to the front of its PATH. Your interactive Terminal aliases and setup may differ. Use explicit paths and an explicit cd when a task depends on a particular tool or directory. A script can read or change files and access the network according to the commands you saved. - Shell: /bin/zsh -f -c, with the saved text passed as the script. - Working directory: your home folder, not a project folder or the script’s export location. - Permissions: your user’s permissions; this is ordinary local shell execution, not a sandbox or automatic administrator session. - Input: standard input is /dev/null, so this runner is not an interactive Terminal session. - Time: up to 60 seconds per run. - Output: combined stdout and stderr, captured up to 256 KiB (shown as 256 KB in the app); excess output is discarded and marked as limited. - Script text: at most 100,000 UTF-8 bytes for execution, with no null characters. ## Stop and process-group cleanup Stop, disabling Scripts, a timeout, and quitting Frog cancel execution and clean up the owned process group. Normal completion also terminates remaining descendants in that group so a child does not keep the output pipe or task alive. This makes the runner appropriate for bounded one-shot tasks. Starting a background service with & does not turn it into a persistent Frog service. A nonzero exit status or timeout is reported in the script view. ## What is saved? Script titles and commands persist alongside notes in ~/.config/frog/Toolkit/toolkit-documents.json. They are excluded from configuration exports. The item overflow menu can explicitly export script text as a .sh file. Captured output and run status stay in memory and are not saved with the script. Copy output explicitly places it on the system clipboard, where enabled clipboard tools can observe it. Commands within a script can independently write their own files or logs. Disabling Scripts stops active execution but keeps saved script definitions for when you enable it again. ## Related guides - [Command bar](https://frog.beffa.xyz/docs/command-bar/) - [Choose features](https://frog.beffa.xyz/docs/features/) - [Notes](https://frog.beffa.xyz/docs/notes/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Frog source and published releases](https://github.com/t1llo/frog) --- # Mr. Usage in Frog: AI plan limits, tokens, and cost estimates Canonical page: https://frog.beffa.xyz/docs/mr-usage/ Updated: 2026-10-26 Mr. Usage adds a second macOS menu-bar item with your plan limits, as percentages with small bars or as a meter you choose. Its popup and full dashboard share provider limits and token activity while the feature is enabled. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Enable and read the dashboard This is an integrated optional module; it does not require running the standalone Mr. Usage app. Frog’s model-provider connections are separate from the coding-tool logins used here. An API key configured for a writing rule does not grant subscription-plan information. 1. Turn on Mr. Usage in Features. It is off by default; enabling adds its separate menu-bar item and starts collection. 2. Click the usage readout for its popup, or open Mr. Usage in the sidebar. Select Claude or OpenAI; this also selects the menu-bar provider. 3. For Claude, choose a login source: Claude Code, Claude Desktop, OpenCode, Pi, or Automatic. Claude Code, OpenCode, and Pi use an existing login from that tool; Claude Desktop reads the limits the Claude app saves on this Mac and sends no request, but the Claude app saves them only now and then; Automatic shows the newer reading and is the dependable choice with a Claude Code login. 4. Read available plan-limit percentages, resets, status, and credits. Use Refresh for an update or Open dashboard for the full view. ## Several Claude accounts When Frog finds a second Claude account on this Mac, such as another Claude app profile or Claude Code folder, the popup and the Mr. Usage page offer to show each one, with Show both and Not now. The same choice is the Show each Claude account switch on the Mr. Usage page. It is off by default. With the switch on, the Accounts list names each account. Give it a label, include it or leave it out, or use Add folder… for a folder Frog did not find. Choose Each account to see the limits side by side or Combined for one set weighted by plan size. With Each account, the menu bar shows each account’s Session or Week limit, such as A 37% B 81%. Frog reads the limits each Claude app profile saves on this Mac; an account known only from the Claude app causes no request. Live readings need a Claude Code sign-in per account, and Set up live readings… explains it before Terminal opens. When an account’s own Claude Code login has run out, its row offers Sign in to Claude Code…, which opens Terminal in that account’s folder. Labels and added folders stay on this Mac. ## Token charts, model costs, and credits Choose Last 24 hours, Last 7 days, or Last 30 days and a metric: API cost, Uncached input, Output, Cache write, or Cache read. The dashboard shows a chart, total, and per-model breakdown. The chart draws the period’s running total as a line, with each day’s or hour’s amount as a thin bar below it; move the pointer over it for exact values. The popup shares the selected metric and period. Local Claude Code, Codex, OpenCode, and Pi records supply supported Claude and OpenAI token activity. The readers deduplicate supported message records rather than treating every transcript row as a new request. Missing logs or incomplete tool records can leave periods empty. API cost is an estimated list-price equivalent, not your subscription charge or an invoice. Models with no known price are identified so missing pricing is visible. Claude extra usage and OpenAI additional-usage credits retain their own provider units rather than being conflated with the token chart’s cost estimate. For OpenAI, choose This Mac or All devices as the activity source. All devices reconciles available complete account days with local records. Account totals can lag and token splits may be estimated; this is not a complete real-time log of every device. ## Choose how the menu-bar item looks Under Menu bar, at the bottom of the Mr. Usage page, each tile shows the item as it will look in your menu bar; click one to use it. Numbers is the readout with percentages and small bars. Steps lights five steps of 20% each, with a partly reached step drawn faint. Bars fills a smooth track, and Columns stands the meters side by side. Without percentages, the item takes less room and does not change with every point. Colors sets Clean, which follows the menu bar like the system’s own icons; Traffic light, green that turns amber from 70% and red from 90%; or Spectrum, which runs from green to red along each meter. Each limit window, such as 5h and 7d, or each Claude account, such as A and B, gets its own row. Without a plan reading, the item still shows the period’s API estimate as text. ## Collection continues with the dashboard closed While enabled, Mr. Usage keeps collecting local activity and polling provider limits even when the dashboard and popup are closed, hidden, or minimized. The separate menu-bar item shows up to two available limit windows; when limits are unavailable, it shows the selected period’s API estimate. Disable Mr. Usage in Features or quit Frog to remove the item, close its popup, and stop collection. Cancellation reaches requests, readers, and aggregation; late replies are discarded. Rate-limit cooldowns and backoff remain in force, including for Refresh. ## Portable display preferences Provider, period, metric, activity source, Claude login-source choice, the several-accounts switch, view, and menu-bar limit, and the menu-bar design and colors are shared between the popup and dashboard and saved in preferences.toolkit.usage. These display choices are included in configuration export/import. Credentials, account details, readings, and polling cooldowns are not exported; another Mac still needs its own originating-tool login. ## Credentials stay with the originating tools Claude usage requests use the selected tool’s existing login. OpenAI plan requests use available ChatGPT credentials from Codex or OpenCode. Frog reads those credentials for the provider request, does not export them, and never uses another tool’s refresh token. When Claude Code’s login has run out, Frog starts Claude Code in the background so that it renews its own login; that sends one minimal request on your Claude plan, at most every 30 minutes and less often while it fails. If Claude Code can no longer renew its login, choose Sign in to Claude Code… in the popup or dashboard: Terminal opens Claude Code’s own sign-in, and Frog picks up the new login. For another tool, sign in again through that tool, then return to Frog. API-key-only logins or a credential store the integration does not support may not expose subscription limits; available local token records can still be useful. Provider usage endpoints receive authenticated usage requests, not transcripts, prompts, notes, or dictation recordings. The integration sends no Frog telemetry and includes no leaderboard or sharing client. Last-good Claude limits, metadata, and request cooldowns use the separate local xyz.beffa.frog.usage defaults domain, outside config.json and the standalone app’s settings. ## When limits or activity are missing Check the selected provider and Claude login source, whether the originating tool is signed in, and whether it has recorded activity in the selected range. Read the popup or dashboard status for authentication or endpoint errors. An expired login is renewed by the tool that owns it; Frog asks Claude Code to do so and offers Sign in to Claude Code… when that is no longer possible. A last-good or log-derived limit snapshot can remain useful when live requests fail, but it is not a fresh response. Available reset windows and credits depend on the provider and account. Keep the feature enabled and allow any reported cooldown to elapse. ## Related guides - [Choose features](https://frog.beffa.xyz/docs/features/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) - [Model providers](https://frog.beffa.xyz/docs/providers/) ## Source documentation - [Frog source and published releases](https://github.com/t1llo/frog) - [Mr. Usage project](https://github.com/t1llo/mr-usage) --- # Frog Stay awake: timed sessions and guided Mac power access Canonical page: https://frog.beffa.xyz/docs/stay-awake/ Updated: 2026-10-25 Stay awake keeps a Mac working during an explicitly started session, including the system setting for lid-closed sleep. Its dedicated page separates the session controls from one-time access setup. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Start a session only when you need one The active session is off by default and never automatically starts at launch. Enabling the feature only exposes its controls. Frog uses the system-wide pmset disablesleep setting rather than an ordinary idle-sleep assertion. A Frog-owned session restores sleep at expiry, normal quit, or when an unplugged battery drops below 20%. Timer and battery checks run approximately once a minute. Choose a duration before enabling; the session page shows its deadline when applicable. 1. Make Stay awake available in Features, then open its page. 2. Complete Access setup if its status is Setup needed. 3. In Session, choose 30 minutes, one hour, four hours, or until Frog quits. Four hours is the default. 4. Turn on Keep this Mac awake. The menu-bar popup has the same control on one line: choose a duration, switch it on, and the popup shows when the session ends. ## Show a cup in the menu bar Under Menu bar on the Stay awake page, Show a cup in the menu bar adds an item of its own while Stay awake is on, in place of the small cup beside Frog’s icon. It is off by default and disappears when the session ends. Choose Cup for the cup alone, Countdown ring for a ring that drains as a timed session runs out, or Time left for the cup with the remaining time, such as 2h 20m. A session until Frog quits keeps a full ring. Click the cup for Turn off Stay awake and Stay awake settings…. ## Complete the guided Terminal access setup The guide manages the dedicated /etc/sudoers.d/frog-awake file and validates it with sudoers tooling. It verifies permission for both commands without changing the sleep setting during setup. Cached administrator authentication alone does not count as configured access. Once authorized, Frog invokes the exact power commands with sudo -n, without a shell or a password prompt. Starting without permission leaves the switch off and offers setup. A successful guide closes its dedicated Terminal window; errors stay visible. 1. Choose Set up access… under Stay awake → Access or in the menu popup. 2. Read the bundled Terminal guide, which explains the two exact power commands and the account-specific sudoers rule. 3. Enter your administrator password directly into Terminal’s sudo prompt when requested. Frog never receives or stores it. 4. Finish validation. Frog checks the effective permissions again; Access shows Ready to use when both commands are allowed. Check access can refresh this status. ```text YOUR_SHORT_USERNAME ALL=(root) NOPASSWD: /usr/bin/pmset -a disablesleep 0, /usr/bin/pmset -a disablesleep 1 ``` ## Stop a session or reset access Turn off Keep this Mac awake to end the session. Disabling Stay awake in Features first restores a Frog-owned session. If restoration fails, Frog reports the problem and retains the feature/session state so you can retry. Stay awake → Access → Reset access… first restores sleep, then opens the Terminal guide. After your confirmation, the guide empties /etc/sudoers.d/frog-awake and validates sudoers. It leaves the empty dedicated file in place and does not edit the main sudoers file. Reset shows Setup needed unless another system policy independently allows the same commands. Run setup again to restore access. If normal quit cannot restore sleep, Frog remains open and reports the error. ## Session ownership and interrupted cleanup Frog reads the actual power setting after changes. If another tool enabled it, the popup shows On outside Frog; Frog does not claim that session or switch it off just because Frog quits. You can explicitly turn it off. A machine-local session marker lets the next launch restore sleep after an interrupted Frog-owned session. A crash or forced termination cannot perform normal quit cleanup, so the system setting may remain enabled until restart or manual restoration. If needed, restore sleep from Terminal with the command below. Lock the Mac separately before closing its lid: sleep control does not lock the screen. Lid behavior still depends on the target Mac and should be checked there after setup. ```sh sudo /usr/bin/pmset -a disablesleep 0 ``` ## Related guides - [Choose features](https://frog.beffa.xyz/docs/features/) - [System monitor](https://frog.beffa.xyz/docs/system-monitor/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Frog source and published releases](https://github.com/t1llo/frog) --- # Frog System monitor: CPU, GPU, disk, and power in the menu bar Canonical page: https://frog.beffa.xyz/docs/system-monitor/ Updated: 2026-10-26 System monitor has a page of its own and adds a System view to Frog’s menu-bar popup. Both show CPU and GPU activity as a graph of the last ten minutes, startup-disk space, disk throughput, and power status. CPU and GPU can also have a menu-bar item of their own. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ![Frog’s menu-bar popup on its System view with example CPU, GPU, disk, and power readings](https://frog.beffa.xyz/screenshots/real/system-monitor.png) Example readings in the System view. ## Open the page or the System view The page and the System view show the same readings; the page draws the graph taller. Disabling the feature removes the page, the Frog/System selector, and the menu-bar item, and stops sampling. 1. Turn on System monitor in Features. It is off by default. 2. Open System monitor in the sidebar. Its page shows the CPU and GPU graph at full width, Disk and Power side by side below it, and then the Menu bar section. 3. Or click Frog’s menu-bar icon and choose System in the popup’s header. Choose Frog to return to the usual controls. ## Show CPU and GPU in the menu bar Turn on Show CPU and GPU in the menu bar, under Menu bar on the System monitor page, to keep CPU above GPU in the menu bar. Choose Steps, Bars, Columns, or Numbers, and Clean, Traffic light, or Spectrum colors; each tile shows the item as it will look. Click the item for the System view. On a Mac whose GPU reports no load, it shows CPU alone. ## What the System view shows A reading that macOS does not provide on your Mac is shown as Unavailable rather than estimated. A Mac without a battery shows its power source instead of a charge level. - CPU: busy time across all logical cores, as the main line of a graph of the last ten minutes. - GPU: current utilization as a second line in the same graph, where macOS reports it. Move the pointer over the graph to read both values at that moment. - Disk: free and total space on the startup volume, plus read and write rates across supported disks. - Power: battery charge and charging state, battery power in watts, thermal state, and Low Power Mode. ## When Frog samples While System monitor is on, Frog records CPU and GPU load every five seconds, or every two with its menu-bar item on, also with the popup and the page closed, so the graph already covers up to the last ten minutes when you open either. While the page or the System view is visible, all readings refresh every two seconds; disk and power are read only then. The graph is kept in memory only. It starts empty when Frog launches or when you turn the feature on, and a pause such as sleep stays a gap in the line. Readings are not saved, exported, or sent anywhere. System monitor needs no Accessibility or Screen Recording permission, no administrator access, and no AI model. ## Related guides - [Choose features](https://frog.beffa.xyz/docs/features/) - [Stay awake](https://frog.beffa.xyz/docs/stay-awake/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Frog source and published releases](https://github.com/t1llo/frog) --- # Frog App cleaner: uninstall Mac apps and the files they leave Canonical page: https://frog.beffa.xyz/docs/app-cleaner/ Updated: 2026-10-16 App cleaner uninstalls an app together with the files it leaves behind in your Library folders: caches, settings, saved state, logs, containers, and background services. You review every item first. Everything goes to the Trash; Frog never deletes anything and never empties the Trash. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Review an app before it goes App cleaner scans only when you pick or drop an app, and nothing moves until you confirm. You can also start in the command bar: type uninstall or remove and the app’s name, such as uninstall example, and choose a row to open the review. 1. Turn on App cleaner in Features. It is off by default. 2. Open App cleaner. It lists the apps in /Applications and ~/Applications with their version and size; Apple’s apps and Frog are not listed. Search by name or bundle ID, sort by name or size, then click an app or press Return. You can also drop an app from Finder onto the page. 3. Review what Frog found. Notices above the list say when the app is running (Frog quits it first), when it comes with its own uninstaller (Open Uninstaller opens it), when it has a system extension, and when some items need Full Disk Access. 4. Tick or untick items; each row shows its size and a Reveal in Finder button. Then choose Move to Trash…, check the list in the confirmation, and choose Move to Trash. ## How sure Frog is that a file belongs to the app Frog groups the files it finds by how sure it is that they belong to the app. Only sure and likely matches start ticked, and the line under each item gives the reason, such as “Named after the bundle ID com.example.app.” Frog never ticks possible matches, items used by other apps, or group containers; tick them yourself when you know they can go. - App: the app itself. - Sure matches: named after the app’s bundle ID, one of its parts, or one of its app groups, or a background service that starts a program inside the app. - Likely matches: named exactly after the app, when that name is distinctive enough. - Possible matches: names that only resemble the app. They appear only with Show possible matches on in Cleaner settings. - Used by other apps: another installed app claims the same name or ID. ## Moving to the Trash Nothing moves until you choose Move to Trash in the confirmation; Return alone does not confirm it. Your own files move with the Mac’s normal Move to Trash. Apps, containers, and items that belong to the system move through Finder, the app first: macOS asks once whether Frog may control Finder, and for system items Finder asks for your administrator password. Frog never sees it. If the app does not move, for example because the password prompt was cancelled, its other files stay where they are, and the review keeps them ticked to try again. Background services whose files move are stopped first. If an app does not quit, Frog asks before it force quits it. The space is freed only when you empty the Trash yourself. ## Put items back Recently moved, the clock button at the top of the page, lists what Frog moved to the Trash in the last 30 days. Put Back returns your own items to their original places. Put Back in Finder opens the Trash for items Frog cannot put back itself, such as items that belong to the system. Remove from this list forgets the record only. Items can be put back only while they are in the Trash. Recently moved marks items that are no longer there, and Put Back leaves alone an item that has since taken the same name in the Trash. After you empty the Trash, the items are gone. ## What App cleaner reads and never touches App cleaner sends nothing over the network. It reads file and folder names, launchd property lists, and the apps’ Info.plist files and code signatures, never the contents of other files. Full Disk Access is optional: without it, protected items stay unread, and those Frog would move itself show Needs Full Disk Access. Finder still moves containers without it. Once you allow it, Frog measures what it could not. The Put Back list stays on this Mac in ~/Library/Application Support/Frog/Cleaner/ and is not exported. Whatever found an item, Frog never offers or moves these: - Apple’s own files, including anything with com.apple. in its name, Shortcuts data, and the system folders. - iCloud Drive and synced folders. - Mail, Messages, Safari, and Photos libraries, and keychains. - A whole Library folder, items already in the Trash, and Frog’s own app, data, and settings. - Items macOS protects, paths that pass through a link, and anything outside the Applications and Library folders it cleans. ## Related guides - [Choose features](https://frog.beffa.xyz/docs/features/) - [Command bar](https://frog.beffa.xyz/docs/command-bar/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [App cleaner guide in the app repository](https://github.com/t1llo/frog/blob/main/docs/cleaner.md) - [App cleaner privacy details](https://github.com/t1llo/frog/blob/main/docs/privacy.md) --- # Let AI agents use Frog: the frog command and agent skills Canonical page: https://frog.beffa.xyz/docs/ai-agents/ Updated: 2026-10-28 Frog includes a frog command that you and your AI coding agents can run in a terminal. A skill tells the agents when and how to use it, so you can ask one to build a Frog plugin for you, arrange windows or add a note. Agent access is off until you turn it on, and the command talks to Frog only through a file in Frog’s data folder, never over the network. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## Turn on agent access The setup assistant has the same choices in its AI agents step. Nothing changes until you press its Turn on and install button; Not now moves on with agent access off. In the configuration file the setting is agents.access. While access is off, frog answers that agent access is off and does nothing. Turning it off again closes the connection at once. 1. Open Settings → Agents and switch on Let AI agents use Frog. 2. Beside Command line tool, press Install. Frog links ~/.local/bin/frog to the tool inside Frog.app, so the link follows Frog’s updates. 3. Press Install beside each skill row you want: Claude Code, and Codex, Gemini CLI, pi, OpenCode. A row whose agents Frog did not find on this Mac says Not found; you can still install it for an agent you set up later. 4. Ask your agent to do something with Frog, such as arranging two windows side by side. ## Put frog on your PATH The link lives in ~/.local/bin, which must be on your shell’s PATH. When none of your shell’s startup files mentions that folder, Settings shows the line to add, with a Copy line button. For zsh, add it to ~/.zshrc: Frog only reads those files to decide whether to show the hint; it never runs or changes them. Without the link, run the tool by its full path, /Applications/Frog.app/Contents/Helpers/frog. Frog never replaces or removes a ~/.local/bin/frog it did not make, and Relink appears when the link leads to another copy of Frog. ```sh export PATH="$HOME/.local/bin:$PATH" ``` ## Skills for Claude Code, Codex, and other agents The skill is a SKILL.md file in the Agent Skills format, named frog. It describes when to use Frog and points the agent to frog help for the commands, so an installed skill keeps working when Frog gains commands. Settings installs it in two folders, which together reach every supported agent once: - ~/.claude/skills/frog: Claude Code. - ~/.agents/skills/frog: Codex, Gemini CLI, pi, and OpenCode, which share this folder. - Update appears when a newer Frog brings a newer skill. Remove deletes only the SKILL.md Frog wrote, then the frog folder if nothing else is left in it. - A frog skill Frog did not write, or a link in place of the folder or its SKILL.md, is never replaced or removed; Settings shows it in Finder instead. ## What agents can do frog help lists every command by group, and frog help followed by a command explains its options with examples. The running app answers it, so it always matches the version of Frog you have. A group marked (off) belongs to a feature that is switched off; frog features enable followed by the feature turns it on. - Frog: status, version, features, and opening Frog’s pages. - Windows: list windows and displays, apply a layout such as left-half, move or resize a window to exact points, focus a window, and list or open apps. These commands use the Accessibility permission Frog already has. - Scripts: list your saved scripts, show one, or run one by name with a timeout. - Notes: list and read notes, fill in a note’s variables with notes show --expand, add notes, and append to them. - Clipboard: list recent clipboard history or copy text. - Writing rules: list your rules and run one on text. - Stay awake, System monitor, and Mr. Usage: start or stop a session, and read CPU, GPU, memory, and AI plan usage. ```sh frog status frog help windows layout frog windows list --json frog windows layout left-half --app Safari frog features enable scripts pbpaste | frog notes add "Meeting" --stdin ``` ## Options and exit codes - --json prints machine-readable output for agents; the plain output is for people. - --stdin passes standard input as the command’s text. - Relative paths are read from the folder you run frog in. - When Frog is not running, frog starts it in the background and waits for it. - Exit code 0: done. 1: the command failed, and standard error says why. 2: unknown command or wrong arguments. 69: Frog cannot be reached, usually because agent access is off. ## Security and privacy - Agent access is off by default. Only you can turn it on, in Settings or the setup assistant; no frog command can. - frog talks to Frog through a Unix socket in Frog’s data folder, ~/Library/Application Support/Frog/agent.sock, that only your user account can open. Nothing listens on the network. - While access is on, any program running as your user can use every frog command, the same as anything that can already run commands in your shell. That includes running your saved scripts with your permissions, reading your notes and clipboard history, and changing Frog’s settings. Turn access off when you do not want agents to have this. - frog asks for no new permission, and Frog sends nothing anywhere for it. The skill files and the link are files in your home folder, and Settings removes them again. ## Related guides - [Saved scripts](https://frog.beffa.xyz/docs/scripts/) - [Windows](https://frog.beffa.xyz/docs/window-management/) - [Configuration](https://frog.beffa.xyz/docs/configuration/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Frog source and published releases](https://github.com/t1llo/frog) - [Frog agents guide in the app repository](https://github.com/t1llo/frog/blob/main/docs/agents.md) - [Agent Skills format](https://agentskills.io/) --- # Frog plugins: add features of your own, built with your AI agent Canonical page: https://frog.beffa.xyz/docs/plugins/ Updated: 2026-10-26 A plugin adds a feature of your own to Frog: a page in the sidebar, commands in the command bar, or both. Ask an AI agent with the Frog skill to build one, or write it yourself. Plugins run in a sandbox and do only what you approve. They arrived in Frog 1.0.40. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## What a plugin is A plugin is a folder with a plugin.json manifest and web files: HTML, CSS, JavaScript and images. Frog shows the plugin’s page in a sandboxed web view inside its window. The page talks to Frog through a frog object in JavaScript, and every call is checked against the permissions you approved. Plugins run only on your Mac, and sharing one is up to you. The manifest names the plugin and says what it needs: - id: lowercase letters, digits, dots and hyphens, 3 to 64 characters, such as com.example.word-counter. It never changes between versions. - name, up to 40 characters, is shown in the sidebar. description is one sentence of up to 200 characters. - version is major.minor.patch, such as 1.2.0. frog is the oldest Frog version the plugin works with. - symbol is an SF Symbol name for the sidebar, puzzlepiece.extension unless you choose another. entry is the page Frog opens: index.html unless you name another, or null for a plugin with commands only. - permissions, hosts and scripts say what the plugin may do, as described under Permissions. - commands are command bar rows. Choosing one sends its id to the page; "show": false runs it without opening the page. - A plugin has at most 400 files and 20 MB in all, and no symbolic links. Hidden files and folders, such as .git and .DS_Store, are left out when it is installed or packed. ```json { "id": "com.example.word-counter", "name": "Word counter", "version": "1.0.0", "description": "Counts the words on the clipboard.", "author": "Jane Appleseed", "homepage": "https://github.com/jane/frog-word-counter", "symbol": "textformat.123", "entry": "index.html", "frog": "1.0.40", "permissions": ["clipboard-read", "notifications"], "hosts": [], "scripts": {}, "commands": [ { "id": "count", "title": "Count words on the clipboard", "keywords": "words length" } ] } ``` ## Build one with your AI agent With agent access on and the Frog skill installed, your AI agent can build a plugin for you, check it and install it for your review. It uses the frog plugins commands below, which you can run yourself too. 1. Turn on agent access in Settings → Agents and install the skill for your agent, such as Claude Code or Codex. 2. Ask for the feature you want, such as “build me a Frog plugin that shows my open GitHub pull requests”. 3. The agent starts the plugin from a template, checks it and installs it. Your first install of a plugin waits for you in Frog → Plugins, where you read what it asks for and approve it. 4. Ask for changes. After you approve a plugin, the agent’s updates apply directly while they ask for nothing new. ```sh frog plugins guide the reference for plugin authors frog plugins new --name "Name" start a plugin from a template frog plugins check check the manifest and files frog plugins install install or update it for your review frog plugins logs the page's console and errors frog plugins snapshot a picture of the page, to check its layout frog plugins pack [--output file] a .frogplugin file to share, with its SHA-256 frog plugins list installed plugins and their state frog plugins remove move a plugin to the Trash ``` - [Let AI agents use Frog](https://frog.beffa.xyz/docs/ai-agents/) ## Install and approve a plugin A newly installed plugin waits in Frog → Plugins until you approve it. The review shows the permissions it asks for, the hosts it may reach and the scripts it may run. Only you can approve or turn on a plugin: the frog command can install one for review, but not approve it. Frog records what you approved. An update that asks for a new permission, adds a host or changes a script waits for you to review it again; any other update applies directly. A plugin with scripts waits for review after any change, since its scripts can run any of its files. A plugin with the same id from somewhere else, such as a file or another author’s link, is reviewed as a new install. There are three ways to install one: - From the plugin directory on this website: Install in Frog opens Frog’s review. - From a link someone shared: Frog → Plugins → Install from link, or a frog://plugins/install link, which opens the same review. - From a folder: frog plugins install and the plugin’s folder, which is how your agent installs what it builds. frog plugins remove moves a plugin to the Trash. - [Frog plugin directory](https://frog.beffa.xyz/plugins/) ## Permissions A plugin without permissions can show its page, keep its own storage and receive its commands. Everything else needs a permission that you approve when you install it: - clipboard-read: read the text on the clipboard. Text that password managers mark as concealed is never given. - clipboard-write: put text on the clipboard. - notifications: show a notification. - links: open web links in your browser. - network: send requests with frog.fetch to the hosts in hosts, and only those. - ai: send text to the AI model your Writing rules use by default. A cloud model’s provider bills you for it. - scripts: run the shell scripts listed in scripts, with your user’s full access to this Mac and the permissions you gave Frog, such as Accessibility. Install a plugin with scripts only when you trust its author and have read the scripts. ## What the sandbox enforces - The page loads only from its own folder, at frog-plugin:///. Every other address is blocked, including links, frames, forms, fetch, WebSockets and WebRTC. Network requests go through frog.fetch, which Frog checks against the plugin’s hosts. - WebRTC, WebTransport, DNS prefetching, the browser’s clipboard API, web notifications, geolocation and sharing are off in every frame. Plugins use frog.fetch, frog.clipboard and frog.notify instead. - The page has no cookies or shared website data, and cannot leave its folder or navigate elsewhere. - alert, confirm and prompt show as a sheet on the plugin’s page, naming the plugin, and only while the page is shown. You can turn a plugin’s dialogs off. - A page in the background cannot bring itself forward or write the clipboard. It can do that only right after one of its commands. - Plugins cannot read Frog’s settings, notes, history, keys or other plugins’ storage. - Scripts run with /bin/zsh from the plugin’s data folder. They stop after 60 seconds, and their output is cut at 1 MB. A script runs only while every file of the plugin is the one you approved. ## The frog JavaScript API The page calls Frog through window.frog. Every function returns a promise, and a call without the permission it needs fails with an error that names the permission. Scripts receive args as $1, $2 and so on, and find input in the FROG_INPUT environment variable. console.log, errors and rejected promises go to the plugin’s log, which frog plugins logs prints. ```js await frog.storage.get("key") // the stored value, or null await frog.storage.set("key", value) // any JSON value; 5 MB per plugin in all await frog.storage.remove("key") await frog.storage.keys() await frog.clipboard.readText() // clipboard-read await frog.clipboard.writeText("text") // clipboard-write await frog.notify("Title", "Body") // notifications await frog.openURL("https://…") // links const response = await frog.fetch("https://api.github.com/…", { method: "GET", headers: {}, body: "", as: "text" // as: "text", "json" or "base64" }) // network: { status, headers, body } await frog.ai("Summarize in one sentence:", text) // ai: the model's answer as text const result = await frog.run("stats", { args: ["--short"], input: "text" }) // scripts: { output, status, truncated } frog.on("command", (id) => { … }) // a command bar row was chosen frog.on("show", () => { … }) // the page came into view frog.show() // bring the plugin's page forward frog.close() // after a command with "show": false frog.info // { id, name, version, permissions, frog } ``` ## Make it look like Frog Frog sets CSS variables on the page for the light or dark appearance and the theme you chose: --frog-ink, --frog-muted, --frog-canvas, --frog-surface, --frog-border, --frog-accent, --frog-critical and --frog-font. A plugin that uses them matches Frog in every theme. Link /_frog/frog.css for Frog’s buttons, inputs, cards and type. frog plugins snapshot takes a picture of the page, so an agent can check its layout. ```html ``` ## Share a plugin frog plugins pack makes a .frogplugin file, a zip of the plugin’s folder, and prints its SHA-256. Publish the file where people can download it over https, such as a GitHub release. Anyone can then install it from Frog → Plugins → Install from link, or with a link of this form, which opens Frog’s review. The URL is percent-encoded, and the SHA-256 names the exact file the link is for. ```text frog://plugins/install?url=&sha256= ``` ## The plugin directory The plugin directory on this website lists plugins people shared, each with its permissions and an Install in Frog button. To have yours listed, open an issue on Frog’s GitHub with the link to its source and its .frogplugin file. Listed plugins are read before they are added, and their files are pinned by SHA-256, but they remain their authors’ work: review the permissions before you install one. - [Browse the plugin directory](https://frog.beffa.xyz/plugins/) - [Open an issue on GitHub](https://github.com/t1llo/frog/issues) ## Related guides - [AI agents](https://frog.beffa.xyz/docs/ai-agents/) - [Command bar](https://frog.beffa.xyz/docs/command-bar/) - [Saved scripts](https://frog.beffa.xyz/docs/scripts/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Frog source and published releases](https://github.com/t1llo/frog) - [Plugin guide in the app repository](https://github.com/t1llo/frog/blob/main/docs/plugins.md) - [Frog plugin directory](https://frog.beffa.xyz/plugins/) --- # 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. or palette.dark. 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) --- # Privacy, local data, and offline operation | Frog for Mac Canonical page: https://frog.beffa.xyz/docs/privacy/ Updated: 2026-10-26 The Frog Mac app has no analytics, telemetry, required account, or Frog backend. Models determine where writing and recordings are processed. Optional toolkit collectors and integrations run only under their feature controls; this website has separate analytics. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## What stays local, and what goes to a provider? To keep dictation fully local, choose local models for both transcription and optional cleanup. Using a local speech model alone does not make a cloud-backed cleanup step local. - Internal writing models process selected text on your Mac using downloaded MLX weights. - Local speech models process recordings on your Mac. Audio is held in process memory and discarded after completion or cancellation. - A cloud writing rule sends the selected text and instructions to its selected provider. - An Explain answer rule sends its model the selection, its instructions, the surrounding text when Include surrounding text is on, the app’s name, the reply language, and earlier turns in the panel. The page or document address is never sent. - An external speech model receives the microphone recording for transcription. - Cloud transcript cleanup sends the transcript and instructions to the selected text provider. - Ollama and LM Studio process requests at the endpoint you configure; a localhost endpoint runs on your Mac. ## Credentials, settings, and history Direct provider API keys are stored in macOS Keychain. Basic settings live in ~/.config/frog/config; complex rules, connections, and custom models live beside it in config.json. Downloaded weights and private data are separate and excluded from configuration exports. Result history is off by default. When enabled, it stores text results locally, with configurable retention and entry limits of up to 30 days and 200 records. Audio files are not added to history. Turning history off stops new records; existing records remain until cleared or expired. Installed coding tools own their authentication and credential refresh. Frog invokes supported CLIs without importing their credentials into Frog’s Keychain. Their selected providers can receive the text and instructions. OpenCode keeps its own CLI session history even when Frog history is off; Frog’s temporary request files are removed. The Frog history switch does not control another tool’s retention. A processed result is placed on the system clipboard. Clipboard managers can observe clipboard contents, including temporary copies used to work with selections in some applications. ## Local aggregate statistics Settings → Statistics records device-local aggregates: recording count, microphone duration, word count, rule categories, and tool counts. Collection defaults to enabled and can be paused or reset. This is separate from opt-in result history and Mr. Usage; no network requests or telemetry are involved. The statistics.json file in ~/Library/Application Support/Frog/ contains all-time counters and up to 365 daily buckets. It stores no transcripts, rule names, app names, queries, provider identities, individual event timestamps, or event logs. Existing history is not backfilled. The page offers all-time, 7-day, and 30-day views; words per minute uses total words divided by total microphone time. Pausing retains existing totals but stops new writes. Reset clears counters and daily buckets while preserving the collection switch; reset recovery from an unreadable file starts paused. The file and collection switch are device-local and excluded from configuration exports. ## Search, clipboard, and private toolkit documents - Command-bar queries search local app names, available window titles, Spotlight filenames, and enabled tools. They are not sent to an LLM. Running a cloud-backed rule is a separate explicit action. - Learn from your choices, off by default, keeps typed command-bar text (up to 32 characters) and the rows you picked in ~/Library/Application Support/Frog/command-choices.json, readable only by you. It is never exported or sent; Forget learned choices… deletes it. - Clipboard is off by default and keeps at most 100 text items, with bounded available formatting, in memory only. It clears on disable or quit and never becomes saved history or exported configuration. - Concealed/transient-marked clipboard text starts hidden and is excluded from command-bar previews. This is not universal password detection or encryption: unmarked passwords can appear as ordinary text. - Notes and script text persist in ~/.config/frog/Toolkit/toolkit-documents.json with user-only file permissions. This separate local JSON file is not an encrypted vault and is not in configuration exports. - Note variables read the current clipboard only when you copy a note or paste it from the command bar. Notes that came from the shelf keep file references; deleting such a note does not delete the original file. - Scripts run explicitly as your user with zsh, a 60-second limit, bounded output, and process-group cleanup. Script output stays in memory unless you copy it; scripts can themselves access files or network services according to their commands. - Explain writes a note only when you press Save to note: the selection, the answer, follow-ups, the app’s name, and the model, plus the address for one note per answer. The surrounding text is not written. - App cleaner reads file and folder names in your Library folders, launchd property lists, and the apps’ Info.plist files and code signatures, never other files’ contents. It moves items only to the Trash after a confirmation, sends nothing, and keeps the Put Back list in ~/Library/Application Support/Frog/Cleaner/removals.json for 30 days. - [Clipboard behavior and controls](https://frog.beffa.xyz/docs/clipboard/) - [Private notes](https://frog.beffa.xyz/docs/notes/) - [Script execution details](https://frog.beffa.xyz/docs/scripts/) ## Optional usage collection and power access Mr. Usage is off by default. Enabling it adds a second menu-bar item and starts local coding-tool readers and provider usage polling, including while the dashboard is closed. Disabling it or quitting Frog removes the item and stops collection. It uses originating-tool credentials, leaves renewing a login to the tool that owns it (starting Claude Code for that with one minimal request when its login has run out), and sends no transcripts to usage endpoints. Cached limit metadata and cooldowns stay in the separate local xyz.beffa.frog.usage defaults domain; only display choices are portable. Stay awake reads local power and battery state and changes the system sleep setting only after guided access setup and an explicit session start. The administrator password is entered into Terminal’s sudo prompt, never Frog. Its machine-local session marker supports interrupted-session cleanup and is not exported. Disabling a feature stops its owned shortcuts, polling, observers, panels, and tasks as applicable. It keeps configuration and saved documents; the memory-only clipboard is cleared. Mr. Usage displays your own provider activity, not telemetry sent to Frog. - [Mr. Usage sources and credentials](https://frog.beffa.xyz/docs/mr-usage/) - [Stay awake sessions and access](https://frog.beffa.xyz/docs/stay-awake/) ## Accessibility and window information Accessibility lets Frog read a selection you explicitly invoke a rule on and attempt replacement in the original field. Frog validates the target rather than continuously recording typing. The window switcher uses Accessibility for window titles and activation. Window identities and recent-use order remain in process memory and are not sent to providers or included in history, logs, or configuration exports. The switcher does not capture screenshots. With the selection bubble on, Frog watches mouse clicks, scrolling, and the Shift key in other apps, and reads a new selection through Accessibility in memory only. It never copies the selection and never shows in password fields, excluded apps, games, or while secure input is on. While an answer panel is open, Frog watches key presses in other apps for the Escape key only. While drag to screen edges or Shift zones are on, Frog watches mouse-button and drag events to notice a window drag, without recording them. It then reads the position and size of the window under the pointer a few times at most and reads no window titles. ## AI agents and the frog command Agent access is off by default. While Let AI agents use Frog is on, Frog answers the frog command through ~/Library/Application Support/Frog/agent.sock, a socket only your user account can open; nothing listens on the network. Any program running as your user can then use every command, including running your scripts and reading notes and clipboard history, the same as anything that can already run commands in your shell. Frog sends nothing anywhere for agents. What an agent does with what it reads follows that agent and its model provider. The skill files and the ~/.local/bin/frog link are files in your home folder that Settings installs and removes. - [Let AI agents use Frog](https://frog.beffa.xyz/docs/ai-agents/) ## Downloads and app updates still use the network Explicit internal-model downloads fetch files from their model repositories and download infrastructure. Adding a custom model source checks public repository metadata before you separately choose to download weights. Frog’s updater checks the GitHub release feed and downloads updates. Automatic update checks and downloads are configurable. These requests do not contain your writing, microphone recordings, or provider API keys. This website counts page views and four named events with a self-hosted Umami and loads Umami’s recorder, which collects heatmaps and session replays when they are switched on for the website. Neither script sets cookies or keeps a visitor identifier in the browser. Website analytics is separate from the Mac app, which has no analytics or telemetry. The website does not record a microphone or call a model provider. ## Related guides - [Explain](https://frog.beffa.xyz/docs/explain/) - [Clipboard](https://frog.beffa.xyz/docs/clipboard/) - [Mr. Usage](https://frog.beffa.xyz/docs/mr-usage/) - [Saved scripts](https://frog.beffa.xyz/docs/scripts/) - [Configuration](https://frog.beffa.xyz/docs/configuration/) ## Source documentation - [Full app privacy documentation](https://github.com/t1llo/frog/blob/main/docs/privacy.md) - [App cleaner reads and moves](https://github.com/t1llo/frog/blob/main/docs/cleaner.md) - [Local aggregate statistics](https://github.com/t1llo/frog/blob/main/docs/statistics.md) - [Installed coding-tool privacy and retention](https://github.com/t1llo/frog/blob/main/docs/local-tool-providers.md) --- # Frog toolkit FAQ: availability, features, privacy, and setup Canonical page: https://frog.beffa.xyz/docs/faq/ Updated: 2026-10-26 Quick answers about the Frog toolkit and the published Mac app. Follow the feature guides for detailed steps and the release notes for the features in your download. These guides describe Frog 1.0.42, the published download as of October 29, 2026. Download links lead to the latest published release. ## What is Frog? Frog is a configurable native macOS toolkit. The toolkit combines writing, Explain, dictation, models, shortcuts, window management and switching, clipboard, command search, notes, scripts, a menu-bar organizer, App cleaner, optional Mr. Usage, Stay awake, and System monitor. Enable the tools you use in Features. ## Does the latest download include everything in these guides? Yes. As of October 27, 2026, the published release is Frog 1.0.40. Frog 1.0.28 added Explain, the Windows page, and App cleaner, each off by default, as well as learning from your choices in the command bar and several Claude accounts in Mr. Usage. Frog 1.0.29 lets the Explain page scroll so every setting can be reached, and snaps windows dragged at normal speed. Frog 1.0.30 lets you pin features to the top of the sidebar and move them, reopens the Frog window at the size you left it, and shows the API cost estimate for several Claude accounts instead of loading it forever. Frog 1.0.31 shows the selection bubble in Chrome and Electron apps, lets you choose the rules it offers, and shows each System Settings pane with its own icon in the command bar. Frog 1.0.32 makes Explain’s answers and its page shorter, moves the bubble choice into each rule’s editor, and keeps both Claude accounts listed in Mr. Usage. Frog 1.0.33 shows the selection bubble in Helium, Chrome, Arc and other Chromium browsers that hid their text from it. Frog 1.0.34 fixes the lag those apps, and with them the whole Mac, could show after 1.0.31: Frog no longer switches them to the screen reader’s accessibility mode, and the bubble appears there at the pointer without reading their text. Frog 1.0.35 lets you choose how Mr. Usage looks in the menu bar, can show CPU and GPU as a menu-bar item of their own, and can show a cup in the menu bar while Stay awake is on. Frog 1.0.36 keeps the menu-bar design you choose on the Mr. Usage page, which 1.0.35 reset to Numbers. Frog 1.0.37 gives every feature its own page with all its settings, among them new System monitor, Clipboard, and Window switcher pages, and leaves Features to turning tools on and off. Frog 1.0.38 adds the frog command and a skill so AI agents such as Claude Code and Codex can arrange windows, run your scripts, and use your notes, off until you turn it on in Settings → Agents. Frog 1.0.39 folds Snippets and Shelf into Notes, where a note can paste from the command bar, and moves the Quick actions text tools into the command bar. Frog 1.0.40 adds plugins: features of your own that your AI agent can build, run in a sandbox, and share as one file. ## Does System monitor run in the background? Only for the graph. While enabled, it records CPU and GPU load every five seconds so its page and the System view already show the last ten minutes when you open them. With Show CPU and GPU in the menu bar on, CPU and GPU are read every two seconds instead. Disk and power are read every two seconds only while the page or the System view is open. The graph stays in memory; nothing is saved or sent. ## Where did the settings move? Since Frog 1.0.37, every feature that is on has its own page with all its settings, including System monitor, Clipboard, and Window switcher. Features only turns tools on and off, with Open beside those that are on. Recording settings (microphone, muting, the Cancel recording shortcut) are on the Dictation page below its rules, and model memory and storage are on Models → Local models below the model list. Copied text is on the Clipboard page; History shows only Frog’s own activity: saved writing results, answers, and dictation. Windows has its own page while that feature is on; otherwise layouts are under Shortcuts → Windows. Shortcuts groups Application and Other (system actions). History, Models, Features, and Settings stay pinned below the feature list; local Statistics is inside Settings. ## Where did Snippets, Shelf, and Quick actions go? Frog 1.0.39 folded them into other features. Snippets are notes with Paste from command bar turned on, and each shelf item is a note that keeps its text and files. Notes is turned on for you if you used either. Generate UUID, Clean clipboard URL, and Base64 encode and decode are command bar rows; Lock screen is in the command bar while Shortcuts is on, and Frog’s appearance is in Settings. ## What happens when I disable a feature? Its navigation and commands disappear and its owned work stops, including relevant shortcuts, panels, tasks, observers, and polling. Settings and saved documents remain for re-enabling. Clipboard is deliberately memory-only and is cleared when disabled. Disabling Stay awake first restores a Frog-owned power session; if restoration fails, Frog reports the problem instead of discarding ownership. ## Does Frog work offline? Yes, when you use downloaded local models for all processing steps. Built-in inference requires Apple silicon and an initial download. Cloud rules, downloads, and update checks need a network connection. A local dictation workflow also needs a local text model if you enable cleanup. ## Does Frog work on Intel Macs? Frog supports macOS 14 or later on Intel and Apple silicon. Built-in speech and text inference requires Apple silicon. Intel Macs can use external providers and native toolkit features that do not require local inference. ## Do I need an account or API key? You do not need a Frog account. Downloaded internal models do not require a cloud API key. Direct external providers may require credentials and charge for API use. Models → Installed tools can use an existing Claude Code, supported Codex 0.159.x, or OpenCode login without a Frog API key. Choose Use model, then select it in a writing or cleanup rule. The tool’s account and provider policies still apply; OpenCode keeps its own session history independently of Frog history. ## Which models can Frog use? Internal speech options include supported Whisper and Parakeet models; internal text options include compatible MLX versions of Qwen3, Llama 3.2, and Gemma 3. Frog also connects to Ollama, LM Studio, OpenAI, Claude, Gemini, and compatible endpoints. Supported model formats and categories matter: not every model file or API supports every type of rule. ## Can Frog rewrite text in every app? Frog works with supported editable fields and depends on the selection information macOS and the target app expose. It checks the original target before replacement. When automatic replacement cannot be completed, the result remains on the clipboard for manual pasting. ## Does Explain change the text I select? No. Explain shows the answer in a panel next to the selection and replaces nothing in the other app. It sends the selection, the rule’s instructions, and, when Include surrounding text is on, up to 1,000 characters around it to the rule’s model. With a local model, this stays on your Mac. ## Is Frog always listening? No. Recording starts when you invoke an audio rule or Record. With local transcription, microphone audio stays in process memory and is discarded after completion or cancellation. Selecting an external speech model sends the recording to that provider. ## Can I configure Frog with a file? Yes. ~/.config/frog/config holds commented key = value settings; config.json beside it holds complex rules and connections. Use Settings → Configuration → Open config, save, then Reload. Comments and symlinks are preserved, and both files can be tracked with chezmoi. Export/Import still supports a complete single JSON document; the split live config.json alone is not a complete export. Credentials, private data, model weights, and permissions stay separate. ## Is the window switcher an AI feature? No. The optional Command–Tab switcher uses native macOS window information and keyboard navigation. It does not need a text or speech model, send window titles to a provider, or capture screenshots. ## Can Frog move and resize windows? Yes. Turn on Windows in Features and choose Snap on its page to drag windows to screen edges and corners, hold Shift for zones, and open the layout picker. Its layout shortcuts cover halves, quarters, thirds, maximize, minimize, center, restore, displays, and full screen. Accessibility access is required; an AI model is not. ## What opens the command bar? Enable Command bar in Features, then press Control–Option–Space. Change the binding on Command bar’s page. Up/Down selects, Return runs, and Escape dismisses. Command–Return copies a note that pastes or a clipboard item instead of attempting to paste it; it is not a universal copy action for every result. Learn from your choices, off by default, lists the rows you pick a bit higher. ## Is clipboard history saved to disk? No. The optional Clipboard tool retains at most 100 text entries in memory and clears them on disable or quit. Saved writing/dictation history is a separate opt-in. Sensitive clipboard markers hide previews, but Frog cannot reliably identify unmarked passwords. ## Does a configuration export include notes or scripts? No. Notes and saved script text live in a separate private local document store. Use the item’s Export action for its text. Notes that came from the shelf point to original files rather than copying them into a synced library. ## When do scripts run? Only when you press Run, choose a saved script in the command bar, or, with agent access on, an AI agent runs one with frog scripts run. They run as your user in zsh, from your home folder, for up to 60 seconds, with output limited to 256 KiB. Stop, feature disable, timeout, and quit clean up the owned process group. A run an agent starts may take up to 600 seconds when it asks for a longer timeout. ## Can AI agents use Frog? Yes, once you turn it on. Settings → Agents installs the frog command and a skill for Claude Code, Codex, Gemini CLI, pi, and OpenCode. Agents can then arrange windows, run your saved scripts, read and add notes, and more. Agent access is off by default, works only for programs running as your user on this Mac, and listens on no network port. - [Let AI agents use Frog](https://frog.beffa.xyz/docs/ai-agents/) ## Can I add my own features to Frog? Yes, since Frog 1.0.40. A plugin adds a page or command-bar commands of your own. Ask your AI agent with the Frog skill to build one, or install one people shared from the plugin directory. Plugins run in a sandbox and do only what you approve. - [Frog plugins](https://frog.beffa.xyz/docs/plugins/) - [Plugin directory](https://frog.beffa.xyz/plugins/) ## Does App cleaner delete files? No. It moves an app and the items you ticked to the Trash after a confirmation and never empties the Trash. Recently moved lists the last 30 days and puts items back while they are still in the Trash. Apple’s files, iCloud Drive, Mail, Photos libraries, and keychains are never offered. ## Is Mr. Usage app telemetry? No. It is an optional menu-bar readout, popup, and dashboard for your own AI limits, tokens, and estimated API costs. Collection continues while enabled, even with the dashboard closed; disable it or quit Frog to stop. Display choices are portable, but credentials and readings are not. Frog leaves renewing a login to the tool that owns it and sends no transcripts to usage endpoints. Website analytics is separate. ## What does Settings → Statistics store? Local aggregate recording, rule, and tool counts, with microphone time, word counts, and all-time/7-day/30-day views. Collection defaults to enabled; pause it to retain totals or Reset to clear them. No transcripts or individual event logs are stored and no data is sent over the network. Statistics is separate from result history and Mr. Usage, and is not synced in configuration. ## Does enabling Stay awake immediately keep my Mac awake? No. The feature makes its session and access page available. Sessions start off, default to four hours, and stop at expiry, normal quit, or below 20% battery while unplugged. One-time setup takes place in Terminal; Frog never receives your administrator password. ## Can I use Frog in the browser? Frog is a native macOS app. Download and install it to rewrite text, dictate, and manage windows. This website provides feature information and setup guides. ## Related guides - [Getting started](https://frog.beffa.xyz/docs/getting-started/) - [Configuration](https://frog.beffa.xyz/docs/configuration/) - [Privacy and offline use](https://frog.beffa.xyz/docs/privacy/) ## Source documentation - [Frog source and release information](https://github.com/t1llo/frog) - [App documentation](https://github.com/t1llo/frog/tree/main/docs)