Mit settings.json konfigurieren

#Wo die Datei liegt

Der Pfad ist auf jedem Betriebssystem derselbe:

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

• Setzen Sie FERRET_CONFIG_DIR (der alte Name MOVIE_ADE_CONFIG_DIR funktioniert ebenfalls), um einen anderen Ordner zu verwenden, z. B. einen in einem Dotfiles-Repository. ~ wird aufgelöst.
• Entwicklungs-Builds (pnpm dev) verwenden ~/.ferret/dev/, sodass die Arbeit an Ferret selbst nie Ihre echten Einstellungen überschreibt.
• Upgrade von 0.1.0: Beim ersten Start wird die alte <userData>/settings.json in die neuen Dateien kopiert. Die alte Datei bleibt als Sicherung erhalten und wird nie verändert.

Upgrade von MOVIE-ADE: Beim ersten Start werden settings.json, state.json, usage/ und .env von ~/.movie-ade/ nach ~/.ferret/ kopiert. Der alte Ordner bleibt erhalten und wird nicht verändert.

In der App zeigen die Einstellungen oben den Pfad an, zusammen mit settings.json öffnen (bearbeitet die Datei im integrierten Editor mit Vervollständigung aus dem Schema) und Im Ordner zeigen.

#Schema und Validierung

Die erste Zeile von settings.json lautet "$schema": "./settings.schema.json". Editoren wie VS Code und Agents wie Claude Code nutzen sie für Vervollständigung, Validierung und die Beschreibung jedes Felds. Das Schema wird mit der App ausgeliefert und bei jedem Start neben die Datei geschrieben, sodass es immer zur installierten Version passt.

Schlüssel, die Ferret nicht kennt, bleiben beim Speichern durch die App unverändert erhalten. Geöffnete Tabs, die letzte URL und anderer Sitzungszustand werden in state.json gespeichert, nicht hier.

#Kommentiertes Beispiel

JSON kennt keine Kommentare, daher stehen die Erläuterungen unter dem Beispiel. Jedes Feld ist optional; lassen Sie weg, was Sie nicht brauchen.

{
  "$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: Review-Ziele für das URL-Menü. Die erste URL wird beim Öffnen des Projekts geöffnet. id kann ein beliebiger eindeutiger String sein.
• agents.customAgents: ein beliebiges CLI oder Wrapper-Skript. startupAgents listet die Agent-Tabs, die mit einem Projekt geöffnet werden, in dieser Reihenfolge.
• capture.sttEndpoints.compatible: jeder Server, der OpenAIs /v1/audio/transcriptions implementiert (speaches, vLLM, LocalAI …). costLimitUsd: null schaltet das Kostenlimit ab, was bei Ihrer eigenen GPU sinnvoll ist. Siehe Transkription und Kosten.
• organizer: Befunde ordnen wird direkt an einen OpenAI-kompatiblen /v1/chat/completions-Server gesendet (hier Ollama). Mit "runner": "claude-code" oder "codex" verwenden Sie stattdessen Ihr eigenes CLI-Login, mit organizer.cliModels wählen Sie deren Modell.
• decision: das Modell, das prüft, ob jeder Befund behoben wurde. Clef Flash auf einem lokalen Ollama ist kostenlos und liest Screenshots. preset kann auch cloudflare, vercel, typesafe oder custom sein.
• Jeder Anbieter-Block (sttEndpoints.*, organizer.endpoints.*) akzeptiert außerdem timeoutMs, headers und, für Azure, apiVersion.

#Beliebige Anbieter: eigene Endpoints

Presets füllen nur URL und Modell vor. Jede Verbindung (Transkription, Befunde ordnen, Entscheidungsmodell) akzeptiert außerdem beliebige URLs, Modelle, Header und Authentifizierung, sodass Sie jeden Anbieter verwenden können: Cloudflare, ein Gateway, einen Unternehmens-Proxy oder Ihren eigenen Server. Die folgenden Felder haben in allen drei denselben Namen und dieselbe Form.

Transkription mit einem beliebigen OpenAI-kompatiblen /v1/audio/transcriptions-Server, der seinen Schlüssel in einem api-key-Header erwartet:

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

Befunde ordnen mit Cloudflare Workers AI (OpenAI-kompatible Chat Completions), optional über 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" } }
    }
  }
}

Entscheidungsmodell auf Cloudflare Workers AI (Clef Flash) oder mit "preset": "custom" auf einem beliebigen Server, der die System One API spricht. Das Entscheidungsmodell erwartet in endpoint eine vollständige Anfrage-URL (mit eingesetztem {account_id} und {model}); alle anderen Felder haben denselben Namen und dieselbe Form wie oben:

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

Legen Sie CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN und die übrigen Variablen in ~/.ferret/.env ab. Die Modellnamen oben sind Beispiele. Prüfen Sie die Modellliste Ihres Anbieters.

#API-Schlüssel

Jeder Anbieter-Block nimmt einen Schlüssel auf eine von drei Arten entgegen. Der zuerst gefundene gilt:

1. "apiKey": "…": der Schlüssel im Klartext in settings.json. Jeder, der die Datei lesen kann, kann auch den Schlüssel lesen, und die Einstellungen zeigen eine Warnung, solange einer vorhanden ist. Vermeiden Sie das, besonders wenn die Datei in einem Dotfiles-Repository liegt.
2. "apiKeyEnv": "OPENAI_API_KEY": der Name einer Umgebungsvariable. Ferret sucht in seiner eigenen Umgebung, dann in der .env des geöffneten Projekts, dann in ~/.ferret/.env. Apps, die über den Finder oder das Startmenü geöffnet werden, sehen keine Variablen, die in Ihrem Shell-Profil exportiert sind; ~/.ferret/.env ist daher der zuverlässige Ort.
3. Der in den Einstellungen gespeicherte Schlüssel: mit dem Schlüsselbund des Betriebssystems verschlüsselt in <userData>/stt-keys.bin (siehe Wo Schlüssel gespeichert werden).

Ferret liest eine Umgebungsvariable nur, wenn Sie sie in apiKeyEnv angeben. Schlüssel werden nie protokolliert, nie in der Oberfläche angezeigt und nie in Absturzberichte aufgenommen.

#Live-Reload

Ferret überwacht settings.json. Ändert sich die Datei, liest die App sie neu ein, prüft sie gegen das Schema und wendet sie an: Theme, Sprache, Layout, Agents, Projekte und KI-Endpoints werden ohne Neustart aktualisiert, und die Seite „Einstellungen“ wird neu geladen.

• Enthält die Datei einen JSON-Syntaxfehler oder einen Wert vom falschen Typ, wird nichts aus dieser Bearbeitung übernommen. Die App behält die letzten gültigen Einstellungen, zeigt den Fehler mit Zeilennummer an und überschreibt Ihre Datei nicht, bis Sie den Fehler behoben haben.
• Wenn die App selbst speichert (weil Sie etwas in den Einstellungen geändert haben), schreibt sie in eine temporäre Datei und benennt diese in settings.json um, sodass ein Absturz nie eine halb geschriebene Datei hinterlässt.

#Ferret von Ihrem Coding-Agent konfigurieren lassen

Fügen Sie Folgendes in Claude Code, Codex oder einen anderen Agent ein, der Dateien bearbeiten kann:

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

Derselbe Prompt mit Ihren tatsächlichen Pfaden steht unter Einstellungen → Ferret von Ihrem Coding-Agent konfigurieren lassen, mit einer Schaltfläche Prompt kopieren.