Configurare con settings.json

#Dove si trova il file

Il percorso è lo stesso su ogni sistema operativo:

~/.ferret/settings.json          # your settings (edit this)
~/.ferret/settings.schema.json   # JSON Schema, rewritten by the app on launch
~/.ferret/state.json             # open folder, last URL, open tabs (managed by the app)
~/.ferret/.env                   # optional: API keys referenced by apiKeyEnv

• Imposta FERRET_CONFIG_DIR (funziona anche il vecchio nome MOVIE_ADE_CONFIG_DIR) per usare un'altra cartella, ad es. una dentro un repository di dotfile. ~ viene espanso.
• Le build di sviluppo (pnpm dev) usano ~/.ferret/dev/, così lavorare sul codice di Ferret non riscrive mai le tue impostazioni reali.
• Aggiornamento dalla 0.1.0: al primo avvio, il vecchio <userData>/settings.json viene copiato nei nuovi file. Il vecchio file resta al suo posto come backup e non viene mai modificato.

Aggiornamento da MOVIE-ADE: al primo avvio, settings.json, state.json, usage/ e .env vengono copiati da ~/.movie-ade/ in ~/.ferret/. La vecchia cartella resta al suo posto e non viene modificata.

Nell'app, le Impostazioni mostrano il percorso in alto, con Apri settings.json (lo modifica nell'editor integrato con il completamento dallo schema) e Mostra nella cartella.

#Schema e validazione

La prima riga di settings.json è "$schema": "./settings.schema.json". Editor come VS Code e agent come Claude Code la usano per il completamento, la validazione e la descrizione di ogni campo. Lo schema è incluso nell'app e viene scritto accanto al file a ogni avvio, quindi corrisponde sempre alla versione installata.

Le chiavi che Ferret non conosce vengono mantenute così come sono quando l'app salva. Le schede aperte, l'ultimo URL e il resto dello stato della sessione sono conservati in state.json, non qui.

#Esempio commentato

JSON non ammette commenti, quindi le note sono sotto l'esempio. Ogni campo è facoltativo; tralascia ciò che non ti serve.

{
  "$schema": "./settings.schema.json",
  "theme": "dark",
  "locale": "en",
  "projects": [
    {
      "id": "shop",
      "name": "shop",
      "folderPath": "/Users/you/src/shop",
      "kind": "web",
      "urls": [
        { "id": "local", "label": "local", "url": "http://localhost:3000" },
        { "id": "prd", "label": "prd", "url": "https://shop.example.com" }
      ]
    }
  ],
  "agents": {
    "customAgents": [
      { "id": "custom:my-agent", "name": "My agent", "command": "my-agent", "args": "--yes" }
    ],
    "startupAgents": ["claude", "custom:my-agent"]
  },
  "capture": {
    "transcription": "compatible",
    "language": "auto",
    "costLimitUsd": null,
    "sttEndpoints": {
      "compatible": {
        "baseUrl": "http://gpu-box.local:8000/v1",
        "model": "Systran/faster-whisper-large-v3",
        "apiKeyEnv": "WHISPER_SERVER_TOKEN"
      }
    }
  },
  "organizer": {
    "runner": "api:compatible",
    "endpoints": {
      "compatible": { "baseUrl": "http://localhost:11434/v1", "model": "qwen3:14b" }
    }
  },
  "decision": {
    "enabled": true,
    "preset": "ollama",
    "endpoint": "http://localhost:11434/v1/systemone",
    "model": "clef-flash"
  },
  "layout": {
    "panels": {
      "projects": { "dock": "left", "visible": true },
      "terminal": { "dock": "bottom", "visible": true },
      "files": { "dock": "right", "visible": false }
    }
  }
}

• projects[].urls: i target di revisione per il menu degli URL. Il primo si apre all'apertura del progetto. id può essere qualsiasi stringa univoca.
• agents.customAgents: qualsiasi CLI o script wrapper. startupAgents elenca, in ordine, le schede degli agent aperte con un progetto.
• capture.sttEndpoints.compatible: qualsiasi server che implementa /v1/audio/transcriptions di OpenAI (speaches, vLLM, LocalAI…). costLimitUsd: null disattiva il limite di spesa, il che ha senso per una tua GPU. Vedi Trascrizione e costi.
• organizer: Organizza segnalazioni inviato direttamente a un server /v1/chat/completions compatibile con OpenAI (qui Ollama). Usa "runner": "claude-code" o "codex" per usare invece il tuo accesso alla CLI, e organizer.cliModels per sceglierne il modello.
• decision: il modello che verifica se ogni segnalazione è stata risolta. Clef Flash su un Ollama locale è gratuito e legge gli screenshot. preset può essere anche cloudflare, vercel, typesafe o custom.
• Ogni blocco di provider (sttEndpoints.*, organizer.endpoints.*) accetta anche timeoutMs, headers e, per Azure, apiVersion.

#Qualsiasi provider: endpoint personalizzati

Le preimpostazioni si limitano a precompilare URL e modello. Ogni connessione (trascrizione, Organizza segnalazioni, modello di decisione) accetta anche qualsiasi URL, modello, header e autenticazione, quindi puoi usare qualsiasi provider: Cloudflare, un gateway, un proxy aziendale o un tuo server. I campi qui sotto hanno lo stesso nome e la stessa forma in tutti e tre.

Trascrizione con qualsiasi server /v1/audio/transcriptions compatibile con OpenAI che vuole la chiave in un header api-key:

"capture": {
  "transcription": "compatible",
  "sttEndpoints": {
    "compatible": {
      "baseUrl": "https://stt.internal.example.com/v1",
      "model": "whisper-large-v3",
      "authScheme": "header",
      "authHeader": "api-key",
      "apiKeyEnv": "INTERNAL_STT_KEY",
      "headers": { "X-Team": "design" }
    }
  }
}

Organizza segnalazioni con Cloudflare Workers AI (chat completions compatibili con OpenAI), facoltativamente tramite AI Gateway:

"organizer": {
  "runner": "api:compatible",
  "endpoints": {
    "compatible": {
      "baseUrl": "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1",
      "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
      "apiKeyEnv": "CLOUDFLARE_API_TOKEN",
      "headers": { "cf-aig-authorization": { "env": "CF_AIG_TOKEN" } }
    }
  }
}

Modello di decisione su Cloudflare Workers AI (Clef Flash), oppure con "preset": "custom" su qualsiasi server che parla l'API System One. Il modello di decisione accetta un URL di richiesta completo in endpoint (con {account_id} e {model} sostituiti); ogni altro campo ha lo stesso nome e la stessa forma visti sopra:

"decision": {
  "enabled": true,
  "preset": "cloudflare",
  "endpoint": "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}",
  "model": "clef-flash",
  "authScheme": "bearer",
  "apiKeyEnv": "CLOUDFLARE_API_TOKEN",
  "headers": { "cf-aig-authorization": { "env": "CF_AIG_TOKEN" } }
}

Metti CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN e le altre variabili in ~/.ferret/.env. I nomi dei modelli qui sopra sono esempi: controlla l'elenco dei modelli del tuo provider.

#Chiavi API

Ogni blocco di provider accetta una chiave in uno di tre modi. Vale la prima trovata:

1. "apiKey": "…": la chiave in chiaro in settings.json. Chiunque possa leggere il file può leggere la chiave, e le Impostazioni mostrano un avviso finché è presente. Evitalo, soprattutto se il file è in un repository di dotfile.
2. "apiKeyEnv": "OPENAI_API_KEY": il nome di una variabile d'ambiente. Ferret cerca nel proprio ambiente, poi nel .env del progetto aperto, poi in ~/.ferret/.env. Le app aperte dal Finder o dal menu Start non vedono le variabili esportate nel profilo della shell, quindi ~/.ferret/.env è il posto affidabile.
3. La chiave salvata nelle Impostazioni: cifrata con il portachiavi del sistema operativo in <userData>/stt-keys.bin (vedi Dove sono memorizzate le chiavi).

Ferret legge una variabile d'ambiente solo quando la indichi in apiKeyEnv. Le chiavi non vengono mai registrate nei log, mai mostrate nell'interfaccia e mai incluse nei report sugli arresti anomali.

#Ricaricamento in tempo reale

Ferret tiene d'occhio settings.json. Quando cambia, l'app lo rilegge, lo verifica rispetto allo schema e lo applica: tema, lingua, layout, agent, progetti ed endpoint IA si aggiornano senza riavvio, e la pagina delle Impostazioni si aggiorna.

• Se il file ha un errore di sintassi JSON o un valore del tipo sbagliato, non viene applicato nulla di quella modifica. L'app mantiene le ultime impostazioni valide, mostra l'errore con il numero di riga e non sovrascrive il file finché non lo correggi.
• Quando è l'app a salvare (hai cambiato qualcosa nelle Impostazioni), scrive su un file temporaneo e lo rinomina sopra settings.json, così un arresto anomalo non lascia mai un file scritto a metà.

#Fai configurare Ferret al tuo coding agent

Incolla questo in Claude Code, Codex o qualsiasi agent in grado di modificare file:

Edit ~/.ferret/settings.json following the JSON Schema in
~/.ferret/settings.schema.json (read the field descriptions first).
Keep unknown keys and keep the file valid JSON. Never write API keys in
plaintext: set "apiKeyEnv" to an environment variable name instead and
tell me which variable to put in ~/.ferret/.env.
Ferret applies the change as soon as the file is saved.

Task: <what you want, e.g. "use my Ollama at http://localhost:11434 with
qwen3:14b for Organize findings and add a prd URL for the shop project">

Lo stesso prompt, con i tuoi percorsi reali già inseriti, si trova in Impostazioni → Fai configurare Ferret al tuo coding agent, con un pulsante Copia prompt.