frog

Let AI agents use Frog: the frog command and agent skills

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.

Updated Read as Markdown

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.

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.
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.

Source documentation