Ferret
Italiano
Discord (si apre in una nuova scheda) X (si apre in una nuova scheda) GitHub (si apre in una nuova scheda) Download

Usare Ferret

Inviare agli agent

Esegui il tuo coding agent nel terminale integrato e consegnagli una revisione con un clic. Claude Code e Codex sono gli esempi più comuni, ma funziona qualsiasi agent dell'elenco qui sotto, e anche una CLI che aggiungi tu. Puoi anche copiare l'istruzione per un agent che gira altrove, oppure pubblicare la revisione su GitHub.

#Rivedere le segnalazioni

Ogni card nella scheda Segnalazioni consente di:

  • Modificare direttamente titolo e richiesta
  • Alternare Invia / Non inviare
  • Guarda registrazione (salta a quel momento) e Sostituisci immagine (scegli un altro fotogramma)
  • Conferma / Segna come da verificare, Unisci con la successiva, Elimina

Filtra per avanzamento mostra o nasconde le segnalazioni in base allo stato (per esempio Solo quelle in attesa della tua verifica); Mostra tutto rimuove il filtro.

L'intestazione contiene Annulla, Apri cartella, Copia per l'Agent, Invia a GitHub / GitLab, Organizza e Invia all'Agent. Il parlato che non è diventato una segnalazione è elencato in Parlato escluso, dove Ripristina come segnalazione lo recupera.

La scheda Segnalazioni

#Eseguire gli agent nel terminale integrato

Quando un progetto si apre, Ferret avvia una scheda del terminale per ogni agent indicato in Impostazioni → Agent → Avvia all'apertura di un progetto, nella cartella del progetto e nella modalità normale dell'agent. Il valore predefinito è Claude Code e Codex:

claude
codex

In alternativa scegli qualsiasi agent dall'elenco di quelli supportati (si avviano nell'ordine in cui li scegli), oppure nessuno.

Le richieste di autorizzazione restano attive

Registrare o clonare un progetto non fa sì che Ferret se ne fidi. Agent come Claude Code e Codex chiedono la prima volta se ti fidi della cartella, e continuano a chiedere prima di modificare file o eseguire comandi. Per permettere agli agent di saltare richieste di autorizzazione, approvazioni e sandbox in un progetto di cui ti fidi, attiva l'opzione per quel progetto in Impostazioni → Agent → Salta le richieste di autorizzazione e conferma. Ferret aggiunge il flag di salto specifico di ciascun agent, dove è noto; gli agent senza un flag noto mantengono le richieste. L'opzione vale poi solo per gli agent che apri tu stesso nella cartella di quel progetto; gli agent avviati all'apertura del progetto mantengono sempre le richieste. I flag per saltare le autorizzazioni scritti negli argomenti vengono ignorati.

Se non è selezionato alcun agent, si apre una semplice shell. Il menu + apre un Nuovo terminale, avvia uno dei tuoi agent in una nuova scheda oppure porta a Impostazioni Agent…. La sua casella di ricerca trova anche schede, URL salvati e file.

Le schede mostrano lo stato dell'agent: In esecuzione, In attesa di input, Fatto (non letto), Inattivo. Nella barra laterale, un progetto in cui è in esecuzione un agent è contrassegnato, così lo vedi senza cambiare progetto.

Trascinare schede e riquadri del terminale per dividerli, spostarli e trasformarli di nuovo in schede.

Trascina per dividere. Trascina una scheda, oppure un riquadro tramite la sua maniglia (visibile quando una scheda è divisa), e rilasciala:

  • sul quarto esterno del bordo di un riquadro: Dividi a sinistra / Dividi a destra / Dividi in alto / Dividi in basso
  • al centro di un riquadro: Apri come scheda (un riquadro esce dalla divisione e diventa una scheda a sé)
  • sulla sottile fascia attorno all'intera area del terminale: Dividi l'intera area a sinistra e così via (quando ci sono 2 o più riquadri)
  • sulla barra delle schede: Posiziona qui come scheda

I processi continuano a girare mentre li sposti, e una scheda rimasta vuota si chiude. Divisioni da tastiera:

AzionemacOSWindows / Linux
Nuovo terminale⌘TCtrlT
Dividi a destra⌘DCtrlShiftD
Dividi in basso⌘⇧DAltShiftD
Chiudi riquadro / scheda⌘WCtrlW

#Agent supportati

Ferret non è legato a un solo agent. Riconosce i coding agent qui sotto: può avviarli, rilevarli in un terminale per Invia all'Agent e mostrare se sono installati. Impostazioni → Agent li elenca con Installato / Non trovato, un pulsante Installa dove il produttore pubblica un programma di installazione da una riga, e il comando e gli argomenti di ciascuno.

Non è nell'elenco? Impostazioni → Agent → Aggiungi agent personalizzato registra qualsiasi CLI o script wrapper (un nome, un comando e, facoltativamente, il nome del processo usato per riconoscerlo); in alternativa aggiungilo a agents.customAgents in settings.json. Gli agent che girano fuori da Ferret possono usare Copia per l'Agent.

Alcune funzioni dipendono dall'agent e per ora sono limitate a Claude Code e Codex:

  • Account e utilizzo: il passaggio tra più accessi e l'indicatore dei limiti di utilizzo nel footer.
  • Organizza: usa il tuo accesso a Claude Code o Codex, oppure un'API LLM che configuri tu.

#Invia all'Agent / Copia per l'Agent

Dalla scheda Segnalazioni all'agent nel terminale integrato con Invia all'Agent.
  1. Fai clic su Invia all'Agent. Per impostazione predefinita (Automatico (scheda attuale o un agent in esecuzione)) va all'agent nella scheda del terminale attuale, oppure a uno in esecuzione. Usa la freccia accanto al pulsante (Scegli l'agent a cui inviare) per scegliere un agent o una scheda precisi.
  2. Ferret scrive l'istruzione nell'input dell'agent e la invia. Segui l'avanzamento nel terminale.

Se nessun agent è in esecuzione, Ferret ne avvia uno e invia appena è pronto. Non viene inviato nulla mentre l'agent attende una risposta a una richiesta di autorizzazione: rispondi prima nel terminale.

Copia per l'Agent mette la stessa istruzione negli appunti per un agent che gira altrove (un altro terminale, un IDE o un'app). Vengono considerate solo le segnalazioni impostate su Invia. Il video non è mai incluso.

#Verifica di accettazione con un modello di decisione

L'agent corregge le segnalazioni e verifica ciascuna con il modello di decisione finché non passano tutte.

Attiva questa opzione e il tuo coding agent controlla il proprio lavoro rispetto a ogni segnalazione prima di riportarla come Fatto. Ferret non giudica nulla da solo: dà all'agent un modello di decisione (qualsiasi API compatibile con System One) e gli dice, in feedback.md, di ripetere il ciclo finché ogni segnalazione non passa.

  1. L'agent implementa le segnalazioni.
  2. Per ogni segnalazione cattura uno screenshot DOPO (stesso viewport e stesso stato della pagina dell'immagine PRIMA) e invia al modello di decisione una richiesta con il testo della segnalazione, la sua riga "Fatto quando" e le immagini PRIMA/DOPO.
  3. Una segnalazione passa quando P(done) è almeno pari alla soglia (predefinita 0.7) e la scelta è done. L'agent corregge le altre e rivaluta tutte le segnalazioni a ogni giro, e si ferma solo quando ogni segnalazione passa nello stesso giro, oppure per un motivo concreto che deve dichiarare: l'API non è raggiungibile, una segnalazione è fuori ambito, oppure una segnalazione è bloccata con punteggi invariati.
  4. L'elenco finale Fatto / Non fatto include i punteggi di ogni segnalazione e il numero di giri.

Configuralo in Impostazioni → Modello di decisione e attiva Aggiungi la verifica con modello decisionale alle istruzioni dell'agent. Le preimpostazioni si limitano a compilare i campi; ogni campo resta modificabile, e Personalizzato funziona con qualsiasi API compatibile.

PreimpostazioneURL della richiestaModelliChiave
Ollama (predefinito)http://localhost:11434/v1/systemoneclef-flash, clef (leggono immagini); nimble, tev1 (solo testo)nessuna, gratuito
Cloudflare Workers AIhttps://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}clef-flash, clef (leggono immagini)CLOUDFLARE_API_TOKEN (permesso Workers AI); ID account dal campo o da CLOUDFLARE_ACCOUNT_ID
Vercel AI Gatewayhttps://ai-gateway.vercel.sh/typesafe/v1/systemonetypesafe-ai/jev, convaiinnovations/laya (solo testo)AI_GATEWAY_API_KEY
TypeSafehttps://api.typesafe.ai/v1/systemonejev-latest, jev-preview (solo testo)TYPESAFE_API_KEY
Personalizzatoqualsiasi URL completoqualsiasiBearer, un header personalizzato o nessuna; header aggiuntivi consentiti

Per Ollama, installalo (0.35.1 o successivo per Clef / Clef Flash) e scarica il modello in un terminale. Ferret non esegue programmi di installazione:

ollama pull clef-flash

Le chiavi provengono dal campo della chiave (salvata con le altre chiavi API), da una variabile d'ambiente che indichi tu (l'ambiente dell'app, il .env del progetto oppure ~/.ferret/.env), oppure da apiKey in settings.json. Gli header aggiuntivi possono leggere valori dalle variabili d'ambiente con ${VAR}.

Come la chiave resta fuori dai prompt

Gli agent non vedono mai la tua chiave. Ferret esegue un relay locale su 127.0.0.1 e fornisce a ogni terminale FERRET_DECISION_URL (il relay, con un token per terminale), FERRET_DECISION_MODEL e FERRET_DECISION_IMAGES (per una release vengono impostati anche i vecchi nomi MOVIE_ADE_DECISION_*). Il relay aggiunge la chiave e gli header e inoltra la richiesta senza modificarla, quindi prompt, feedback.md e trascrizioni degli agent non contengono segreti. I terminali aperti dopo aver cambiato le impostazioni le recepiscono.

Cloudflare differisce dalla documentazione di System One in due punti (verificati sull'API reale): le immagini devono essere data URI (data:image/jpeg;base64,…, altrimenti 422 "image must be an embedded base64 data URI"), e la risposta è racchiusa come { "result": { … }, "success": true } (gli errori tornano come { "success": false, "errors": [ … ] }). La preimpostazione Cloudflare imposta Codifica immagini su data URI, gli agent la ricevono come FERRET_DECISION_IMAGE_FORMAT, e le istruzioni dicono loro di leggere .result quando è presente. Il relay lascia passare entrambe le direzioni senza modifiche. Per usare una Global API Key invece di un token API, imposta Autenticazione su Nessuna chiave e aggiungi gli header X-Auth-Email: ${CLOUDFLARE_EMAIL} e X-Auth-Key: ${CLOUDFLARE_API_KEY}.

Solo Clef e Clef Flash leggono le immagini. Con un modello solo testo, disattiva Invia immagini PRIMA/DOPO; l'agent giudica allora solo dal testo, il che è meno affidabile.

Ollama e immagini grandi

Ollama 0.35.0 limita le richieste a /v1/systemone a 64 KiB, quindi le richieste con screenshot falliscono con HTTP 413. Le istruzioni dicono all'agent di ridurre entrambe le immagini a una larghezza massima di 1024px in JPEG (qualità circa 70). Se riceve ancora 413, aggiorna Ollama alla 0.35.1 o successiva, oppure passa a Cloudflare Workers AI.

#Utilizzo delle API nel footer

Le chiamate al modello di decisione passano per il relay, quindi Ferret può contarle. La voce del footer accanto all'indicatore di utilizzo degli agent mostra il modello di decisione e le chiamate, i token e il costo di oggi (per esempio clef-flash · 42 calls · 18.3k tok). Fai clic per vedere i dati di oggi e del mese in corso, suddivisi per progetto, per modello e per tipo (decisione / trascrizione / organizzazione), e le ultime 50 chiamate.

Il costo compare solo quando l'API lo riporta (Vercel AI Gateway lo fa) o quando imposti i prezzi per 1M di token in Impostazioni → Modello di decisione; altrimenti mostra "—". Vengono registrati solo metadati (ora, progetto, modello, stato, latenza, dimensione, numero di immagini, token, costo), mai immagini, testo o chiavi, in ~/.ferret/usage/decision-YYYY-MM.jsonl, un file al mese.

#Personalizzare l'istruzione

Modifica Impostazioni → Agent → Istruzioni per l'Agent. Vengono espanse due variabili:

VariabileSi espande in
{{path}}Percorso assoluto di feedback.md
{{relpath}}Percorso relativo al progetto: .ferret/reviews/<id>/feedback.md

Lascialo vuoto per usare l'istruzione predefinita. La lunghezza massima è di 2000 caratteri, e Reimposta istruzioni ripristina quella predefinita. Esempio:

Read {{relpath}} and the PNGs next to it. Fix only findings marked to send, one commit per finding, then run the tests.

L'impostazione è memorizzata come agentPrompt in settings.json.

#Inviare a GitHub o GitLab (Issue / commento a PR o MR)

Invia a GitHub pubblica la revisione come nuova issue oppure come commento a una delle tue pull request aperte. L'autenticazione è delegata alla GitHub CLI (si apre in una nuova scheda). Ferret non legge né memorizza mai un token.

  1. Installa gh: brew install gh (macOS), winget install --id GitHub.cli (Windows), oppure vedi cli/cli (si apre in una nuova scheda).
  2. Impostazioni → GitHub / GitLab → Accedi nel terminale esegue gh auth login --web -h github.com nel terminale integrato.
  3. Fai clic su Invia a GitHub, scegli Crea una nuova Issue o una PR, e controlla Titolo e Corpo (modificabili).
  4. Spunta la casella di conferma, poi Crea Issue oppure Pubblica commento.

Dettagli:

  • Il repository viene ricavato da git remote get-url origin.
  • Ferret esegue gh issue create --repo … --title … --body-file - oppure gh pr comment <n> --repo … --body-file -.
  • Il corpo è feedback.md senza le righe delle immagini (le immagini non vengono caricate), fino a 60.000 caratteri.
  • Le PR candidate sono le tue PR aperte (fino a 30).

Se è impostato GH_TOKEN o GITHUB_TOKEN, gh lo usa per primo, e il pannello delle impostazioni lo segnala.

GitLab. Quando origin è un progetto GitLab (gitlab.com o un GitLab self-managed), lo stesso pulsante invia a GitLab tramite la GitLab CLI (si apre in una nuova scheda) (glab): una nuova issue, oppure un commento a una delle tue merge request aperte. Accedi con Impostazioni → GitHub / GitLab, che esegue glab auth login (con --hostname per un GitLab self-managed) nel terminale integrato. Ferret non legge né memorizza mai il token, e avvisa quando è impostato GITLAB_TOKEN.

Richiesta di stella. Dopo il tuo primo Invia all'Agent, e quando raggiungi 3, 10 e 30 revisioni completate, Ferret può chiederti di aggiungere una stella su GitHub. Lo chiede al massimo 3 volte, ad almeno 3 giorni di distanza, e mai durante una registrazione. Aggiungi stella su GitHub aggiunge la stella tramite il tuo accesso a gh (oppure apre GitHub se gh non è disponibile), e Non chiedere più interrompe le richieste. Puoi anche aggiungere la stella da Aiuto → Aggiungi una stella a Ferret su GitHub.

#Installare gli strumenti CLI e accedervi

Impostazioni → Strumenti CLI elenca gli strumenti da riga di comando di cui i tuoi agent hanno spesso bisogno, mostra quali sono installati e la loro versione, ed esegue il comando ufficiale di installazione o di accesso per il tuo sistema operativo in una nuova scheda del terminale:

  • Hosting Git: gh, glab
  • IA e modelli: Ollama, Cloudflare wrangler
  • Deploy: Vercel, Netlify, Fly.io, Railway, Heroku
  • Cloud e servizi: Supabase, Firebase, Stripe, Google Cloud (gcloud), AWS, Azure, Docker

Se uno strumento non ha un programma di installazione ufficiale da una riga per il tuo sistema operativo, Documentazione apre invece la sua pagina di installazione. Al termine di un'installazione l'elenco si aggiorna da solo.

Aiuta a tradurre questa pagina su GitHub (si apre in una nuova scheda)