Using Ferret

Projects and URLs

A project is a folder (usually your repo root). Each project keeps its own saved URLs, so local, dev, and production are one click apart.

#Add a project

  1. File → Open Project Folder… (⌘O / CtrlO), Add Project in the sidebar, or Add Project… in the title bar project menu.
  2. Choose where the project comes from:
    • On this computer: pick a folder.
    • Clone from GitHub / GitLab: pick one of your repositories (listed through your gh or glab login) or paste a URL, choose the parent folder, and Ferret clones it and opens it.
    • Open over SSH: pick a host from ~/.ssh/config. The terminal and agents run on the remote machine; reviews stay on this computer.

You can also drag a folder from Finder (File Explorer on Windows, your file manager on Linux) and drop it on the project list in the sidebar. The list is highlighted while you drag. Drop a folder, not a file; dropping several folders adds each of them and opens the last one.

The name defaults to the folder name. Adding a folder that is already registered opens it instead (paths are compared case-insensitively on macOS and Windows). From the sidebar menu you can Rename a project or Remove from List. Removing never deletes the folder.

To change the order of the list, drag a project up or down (a line shows where it will go), press ⌥↑ / Alt↑ / ⌥↓ / Alt↓ on a selected project, or use Move Up / Move Down in its menu. The order is saved and kept after a restart.

The filter button next to the review search also sets Sort projects: Manual (drag order), Active first (projects whose agent waits for you, is working, or just finished come first), Recently used, Name, or Date added. If you drag a project while another sort is selected, the list as shown becomes the manual order and the sort switches to Manual (drag order). Click the star on a project row, or Star in its menu, to keep it at the top of the list in every sort; Starred only hides the rest. Stars and the sort are kept after a restart.

Terminals open in the project folder, and reviews are saved under <project>/.ferret/.

#Create a private GitHub repository

To put a project that isn't on GitHub yet into a private repository, right-click it in the sidebar and choose Create private GitHub repo. It uses your gh login, so gh must be installed and signed in. Only GitHub is supported, not GitLab.

  1. Pick the Owner (your account or one of your organizations) and the Repository name (suggested from the folder name; letters, numbers, ., _ and -). You can add a Description (optional).
  2. If the folder has no commits yet, Make a first commit and push it makes a first commit without the files that .gitignore ignores and without files that may hold secrets: .env files (templates such as .env.example are kept), keys such as *.pem or id_rsa, .npmrc, .netrc, credentials.json, *.tfstate and similar. The dialog lists what is left out. Those paths are added to .git/info/exclude, so they stay out of later commits too; your files and .gitignore are not changed. A folder that isn't a git repository yet is initialized with the branch main.
  3. Click Next, check the repository, visibility and push, then click Create. The repository is always private. It becomes the folder's origin, and the folder's commits are pushed.

Ferret doesn't create the repository when the folder already has an origin, when it is inside another git repository (for example a folder in a monorepo), when a repository with that name already exists, when the first commit would hold more than 20,000 files, when git has no user name and email, or when the project is opened over SSH.

The owner picked first is your own account. To use an organization instead, set Owner for new repositories (GitHub) in Settings → Service CLIs (github.defaultOwner in settings.json).

#Save URLs

  1. Open the page in the built-in browser.
  2. Click + (Save current URL) in the browser toolbar. The current URL is pre-filled.
  3. Enter a Name and click Save.

Each saved URL has a kind under Reviewing: App (the app you are building), Design (Figma, Penpot, Canva, a prototype), Doc / spec (Google Docs, Notion, Confluence, a Markdown spec on GitHub, a PDF) or Reference (a competitor's or another external site you can't change). The kind is guessed from the URL and the name, and you can change it. See Review designs and documents, not only code and Use other sites as a reference.

Only http:// and https:// URLs are accepted. For an app URL, the name is guessed from the host if you leave it as suggested:

HostName
localhost, 127.*, ::1, 0.0.0.0, *.localhostlocal
contains dev, develop, developmentdev
contains stg, stage, stagingstg
anything elseprd
Saved URLs in the browser toolbar
Saved URLs in the browser toolbar

#Review targets panel

Switching review targets and pages without stopping the recording.

In Feedback mode, the Review targets panel on the right lists everything you can review for the current project. Switching targets doesn't stop the recording. Toggle the panel with View → Toggle Review Targets (⌘⇧K / CtrlShiftK) or Hide panel.

  • Targets: the project's saved URLs. Under each one is a tree of the pages you have visited on that site. Sites you visited that aren't saved appear as their own groups.
  • Files: the project folder. A file opens as a preview (Markdown and Mermaid rendered, other text read-only), so you can review docs too. The pencil (Open in editor) opens it in the editor.

Filter targets filters targets, pages, and files together, with the same fuzzy matching as Go to File…. In the list, ↑ ↓ Enter or 1–9 switch targets. Open URL… opens a one-off URL, and Save to project URLs keeps it.

Targets come from projects[].urls in settings.json (see the example). Each entry needs a url, a launchCommand (run in a terminal, e.g. to start a desktop app), or a windowMatch (the window to record), and can have a purpose (app, design, doc or reference). Picking a window target before recording sets it as the recording source; while recording, it adds that window to the recording and shows it (see Record several windows at once). Visited pages are remembered per project, on this machine only (up to 200).

#Open and switch environments

Click a saved URL to open it. If the current page is under another saved URL, Ferret keeps the path, query, and hash and swaps only the origin. For example, on http://localhost:3000/pricing?plan=pro, clicking prd opens https://example.com/pricing?plan=pro.

The chip matching the current page (longest prefix) is highlighted. Right-click a chip or use its pencil icon to edit or Delete it. When a project opens and there is no previous URL, its first saved URL loads.

Chips are grouped by kind: app URLs first, then designs, then docs, then references, with a divider and an icon for each kind. Switching to or from a design, a doc or a reference opens its saved URL as is, without carrying the path over.

#Review designs and documents, not only code

Feedback doesn't have to be about code. Anything that opens in the built-in browser can be recorded and marked up with the pen the same way: a Figma or Penpot design, a prototype, a spec in Google Docs or Notion, a design doc on GitHub, a PDF. Save those URLs to the project before the review, next to local and dev.

  1. Open Edit Project… from the sidebar menu (or click + in the browser toolbar) and Add Target.
  2. Paste the URL. A figma.com link becomes Design and a docs.google.com or notion.so link becomes Doc / spec, named Figma or Spec. Change the kind under Reviewing if the guess is wrong (for example a prototype on your own server).
  3. Open the target and sign in once in the built-in browser if the site needs it. The browser keeps its cookies between launches, so you stay signed in.
  4. Record as usual: talk, point, draw on the design or the document.

Findings recorded on a design or a doc are labeled with that kind in Findings and in feedback.md, and the instruction sent to the agent says so. The agent then changes the design or the document instead of the code:

  • If the document lives in the project (a Markdown spec, an ADR), the agent edits that file.
  • If it can't edit it (a Figma file, a Google Doc), the agent doesn't stop to ask you: it sets the finding to To review with a one-line note of the exact change to make, so you can apply it or pass it on.

Example: while reading the pricing spec in Google Docs you circle the plan table and say "the Pro plan is 9,800 yen now, not 8,800". feedback.md lists the finding under the Spec target with Kind: document, and the agent answers with the corrected sentence for the spec rather than touching the pricing page code. Record the spec and the running app in the same recording, and the findings are split by target, so the agent can update the spec first and then the code that implements it.

Unsaved pages on figma.com, docs.google.com, notion.so and similar hosts are recognized too. Files in the project folder (Markdown, Mermaid) are reviewed from the Files list in the Review targets panel.

#Use other sites as a reference

You can also record a competitor's site, or any page whose look you like, and say what to take from it ("use this as a model", "this black background doesn't work"). You can't change that site, so the agent never tries to: it treats those findings as a reference for your own app.

  1. Add the site as a target and pick Reference under Reviewing. A name with "competitor" or "reference" in it (for example Competitor: Acme) picks it for you.
  2. Record as usual, and switch between that site and your app in the same recording if you like.

Findings on a reference site are labeled Reference in Findings and Kind: reference in feedback.md. For each one the agent:

  • adopts what you liked where it fits in your app, and notes where it applied it;
  • checks that your app doesn't do what you disliked, and fixes your app if it does;
  • changes nothing when a remark gives it nothing to act on, and sets the finding to To review with a note such as "External site, no action needed (reference)".

It never edits the external site and never stops to ask you. A finding is also treated as a reference, without picking the kind, when its target's name contains "competitor" or "reference" (or 競合 / 参考), or when it was recorded on an unsaved site whose host doesn't match any of the project's app URLs. localhost and private addresses never count as external, and a project with no app URLs saved doesn't get this guess.

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