Start here

Quick start

Install Ferret, open your project and its dev server URL, record one piece of feedback, and hand it to your coding agent. About five minutes.

#Before you start

Open a page, record, circle and talk, stop, and send the findings to an agent.
  • A coding agent that runs in a terminal, installed and signed in: for example Claude Code (claude), Codex (codex), or Gemini CLI (gemini). Ferret runs it in its built-in terminal. Any agent in the supported list works, and so does any other CLI you add yourself.
  • A web app you can open by URL, e.g. a dev server on http://localhost:3000.
  • A microphone. Feedback is your voice plus the pen. Without a mic, pen circles still become findings, but they have no words.

#1. Install

Download Ferret from the download page and open it. The steps for each OS are on Install.

#2. Open a project and a URL

  1. File → Open Project Folder… (⌘O / CtrlO) and pick your repository root.
  2. Type your dev server URL into the browser's URL bar (⌘L / CtrlL) and press Enter.
  3. Optional: click + (Save current URL) to keep it as a one-click preset such as local, dev, or prd.

Opening a project also starts your agents in terminal tabs in that folder. Out of the box these are Claude Code and Codex; pick the ones you use under Settings → Agents → Start When a Project Opens (see Settings).

#3. Record

  1. Click Record in the title bar, or press ⌘⇧R / CtrlShiftR. The window switches to Feedback mode.
  2. Use the page as usual and say what should change.
  3. Hold ⌥ / Alt (or pick Pen) and drag to circle the spot while you talk about it.
  4. Click Stop or press ⌘⇧R / CtrlShiftR again.

Each moment you speak or circle becomes one finding: a screenshot with your pen marks, the request, the original words, the URL, and the element you pointed at.

#4. Check the findings

After you stop, the window returns to Editor mode and opens the Findings tab.

  • Edit a title or request in place.
  • Toggle Send / Don't send per finding, or Delete.
  • Undo reverts the last edit.

#5. Send to an agent

  1. Click Send to Agent. It goes to the agent in the current terminal tab, or to a running one. The arrow next to the button picks a specific agent or tab.
  2. If no agent is running yet, Ferret starts one first and sends as soon as it is ready.

Ferret types one instruction into the agent's prompt and submits it. By default it begins:

Read "{{path}}" and the image for each finding in the same folder, then implement every finding marked for sending. …

The rest asks the agent to check each change on the actual screen, record its progress per finding, and finish with a Done / Not done list. The agent reads .ferret/reviews/<timestamp>/feedback.md and the PNGs next to it. The video is never sent. Using an agent outside Ferret? Click Copy for Agent and paste.

The default follows the display language. You can replace it in Settings: see Customize the instruction.

#Next steps

Edit this page on GitHub (opens in a new tab)