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
- 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
- File → Open Project Folder… (⌘O / CtrlO) and pick your repository root.
- Type your dev server URL into the browser's URL bar (⌘L / CtrlL) and press Enter.
- Optional: click + (Save current URL) to keep it as a one-click preset such as
local,dev, orprd.
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
- Click Record in the title bar, or press ⌘⇧R / CtrlShiftR. The window switches to Feedback mode.
- Use the page as usual and say what should change.
- Hold ⌥ / Alt (or pick Pen) and drag to circle the spot while you talk about it.
- 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
- 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.
- 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
- Concepts: modes, findings, and what the agent receives
- Transcription and costs: download a free on-device whisper model, or bring your own endpoint
- Keyboard shortcuts