Configurer avec settings.json

#Emplacement du fichier

Le chemin est le même sur tous les OS :

~/.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

• Définissez FERRET_CONFIG_DIR (l'ancien nom MOVIE_ADE_CONFIG_DIR fonctionne aussi) pour utiliser un autre dossier, par exemple dans un dépôt de dotfiles. ~ est développé.
• Les versions de développement (pnpm dev) utilisent ~/.ferret/dev/ : travailler sur Ferret ne réécrit donc jamais vos vrais réglages.
• Mise à niveau depuis la 0.1.0 : au premier lancement, l'ancien <userData>/settings.json est copié dans les nouveaux fichiers. L'ancien fichier est laissé en place comme sauvegarde et n'est jamais modifié.

Mise à niveau depuis MOVIE-ADE : au premier lancement, settings.json, state.json, usage/ et .env sont copiés de ~/.movie-ade/ vers ~/.ferret/. L'ancien dossier est laissé en place et n'est pas modifié.

Dans l'application, les Réglages affichent le chemin en haut, avec Ouvrir settings.json (pour le modifier dans l'éditeur intégré avec la complétion du schéma) et Afficher dans le dossier.

#Schéma et validation

La première ligne de settings.json est "$schema": "./settings.schema.json". Les éditeurs comme VS Code et les agents comme Claude Code s'en servent pour la complétion, la validation et la description de chaque champ. Le schéma est livré avec l'application et écrit à côté du fichier à chaque lancement : il correspond donc toujours à la version installée.

Les clés que Ferret ne connaît pas sont conservées telles quelles lorsque l'application enregistre. Les onglets ouverts, la dernière URL et les autres éléments d'état de session sont conservés dans state.json, pas ici.

#Exemple commenté

Le JSON n'accepte pas les commentaires : les explications se trouvent donc sous l'exemple. Tous les champs sont facultatifs ; omettez ce dont vous n'avez pas besoin.

{
  "$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 : les cibles de relecture du menu des URL. La première s'ouvre à l'ouverture du projet. id peut être n'importe quelle chaîne unique.
• agents.customAgents : n'importe quelle CLI ou script d'enrobage. startupAgents liste, dans l'ordre, les onglets d'agent ouverts avec un projet.
• capture.sttEndpoints.compatible : n'importe quel serveur qui implémente /v1/audio/transcriptions d'OpenAI (speaches, vLLM, LocalAI…). costLimitUsd: null désactive le plafond de coût, ce qui est logique pour votre propre GPU. Voir Transcription et coûts.
• organizer : Organiser les remarques est envoyé directement à un serveur /v1/chat/completions compatible OpenAI (ici Ollama). Utilisez "runner": "claude-code" ou "codex" pour passer plutôt par votre propre connexion CLI, et organizer.cliModels pour choisir leur modèle.
• decision : le modèle qui vérifie si chaque remarque a été corrigée. Clef Flash sur un Ollama local est gratuit et lit les captures d'écran. preset peut aussi valoir cloudflare, vercel, typesafe ou custom.
• Chaque bloc de fournisseur (sttEndpoints.*, organizer.endpoints.*) accepte aussi timeoutMs, headers et, pour Azure, apiVersion.

#N'importe quel fournisseur : endpoints personnalisés

Les préréglages ne font que préremplir l'URL et le modèle. Chaque connexion (transcription, Organiser les remarques, modèle de décision) accepte aussi n'importe quelle URL, n'importe quel modèle, n'importe quels en-têtes et n'importe quelle authentification : vous pouvez donc utiliser n'importe quel fournisseur, que ce soit Cloudflare, une passerelle, un proxy d'entreprise ou votre propre serveur. Les champs ci-dessous ont le même nom et la même forme dans les trois.

Transcription avec n'importe quel serveur /v1/audio/transcriptions compatible OpenAI qui attend sa clé dans un en-tête 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" }
    }
  }
}

Organiser les remarques avec Cloudflare Workers AI (chat completions compatible OpenAI), éventuellement via 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" } }
    }
  }
}

Modèle de décision sur Cloudflare Workers AI (Clef Flash), ou avec "preset": "custom" sur n'importe quel serveur qui parle l'API System One. Le modèle de décision prend une URL de requête complète dans endpoint (avec {account_id} et {model} remplis) ; tous les autres champs ont le même nom et la même forme que ci-dessus :

"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" } }
}

Placez CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN et les autres variables dans ~/.ferret/.env. Les noms de modèles ci-dessus sont des exemples. Consultez la liste des modèles de votre fournisseur.

#Clés d'API

Chaque bloc de fournisseur accepte une clé de l'une des trois façons suivantes. La première trouvée l'emporte :

1. "apiKey": "…" : la clé en clair dans settings.json. Quiconque peut lire le fichier peut lire la clé, et les Réglages affichent un avertissement tant qu'elle est présente. À éviter, surtout si le fichier se trouve dans un dépôt de dotfiles.
2. "apiKeyEnv": "OPENAI_API_KEY" : le nom d'une variable d'environnement. Ferret cherche dans son propre environnement, puis dans le .env du projet ouvert, puis dans ~/.ferret/.env. Les applications ouvertes depuis le Finder ou le menu Démarrer ne voient pas les variables exportées dans le profil de votre shell : ~/.ferret/.env est donc l'emplacement fiable.
3. La clé enregistrée dans les Réglages : chiffrée avec le trousseau de l'OS dans <userData>/stt-keys.bin (voir Où les clés sont stockées).

Ferret ne lit une variable d'environnement que si vous la nommez dans apiKeyEnv. Les clés ne sont jamais journalisées, jamais affichées dans l'interface et jamais incluses dans les rapports de plantage.

#Rechargement à chaud

Ferret surveille settings.json. Lorsqu'il change, l'application le relit, le vérifie par rapport au schéma et l'applique : thème, langue, disposition, agents, projets et endpoints d'IA se mettent à jour sans redémarrage, et la page Réglages s'actualise.

• Si le fichier contient une erreur de syntaxe JSON ou une valeur du mauvais type, rien de cette modification n'est appliqué. L'application garde les derniers réglages valides, affiche l'erreur avec son numéro de ligne et n'écrase pas votre fichier tant que vous ne l'avez pas corrigé.
• Lorsque l'application enregistre elle-même (vous avez modifié quelque chose dans les Réglages), elle écrit dans un fichier temporaire puis le renomme par-dessus settings.json : un plantage ne laisse donc jamais un fichier à moitié écrit.

#Laisser votre agent de code configurer Ferret

Collez ceci dans Claude Code, Codex ou n'importe quel agent capable de modifier des fichiers :

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">

Le même prompt, avec vos chemins réels déjà remplis, se trouve sous Réglages → Laissez votre agent de code configurer Ferret, avec un bouton Copier le prompt.