settings.json से कॉन्फ़िगर करें

#फ़ाइल कहाँ रहती है

Path हर 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

• कोई दूसरा फ़ोल्डर इस्तेमाल करने के लिए, जैसे किसी dotfiles repo के अंदर का फ़ोल्डर, FERRET_CONFIG_DIR सेट करें (पुराना नाम MOVIE_ADE_CONFIG_DIR भी काम करता है)। ~ expand किया जाता है।
• Development builds (pnpm dev) ~/.ferret/dev/ इस्तेमाल करते हैं, ताकि Ferret पर काम करते समय आपकी असली सेटिंग्स कभी न बदलें।
• 0.1.0 से अपग्रेड करने पर: पहले launch पर पुरानी <userData>/settings.json नई फ़ाइलों में कॉपी की जाती है। पुरानी फ़ाइल backup के रूप में अपनी जगह पर रहती है और कभी बदली नहीं जाती।

MOVIE-ADE से अपग्रेड करने पर: पहले launch पर settings.json, state.json, usage/ और .env को ~/.movie-ade/ से ~/.ferret/ में कॉपी किया जाता है। पुराना फ़ोल्डर अपनी जगह पर रहता है और बदला नहीं जाता।

ऐप में Settings सबसे ऊपर path दिखाता है, साथ में settings.json खोलें (schema completion के साथ बिल्ट-इन editor में संपादित करने के लिए) और फ़ोल्डर में दिखाएँ।

#Schema और validation

settings.json की पहली लाइन "$schema": "./settings.schema.json" है। VS Code जैसे editors और Claude Code जैसे agents इसे completion, validation और हर field के विवरण के लिए इस्तेमाल करते हैं। Schema ऐप के अंदर ही आता है और हर launch पर फ़ाइल के बगल में लिखा जाता है, इसलिए यह हमेशा इंस्टॉल किए गए version से मेल खाता है।

जिन keys को Ferret नहीं जानता, वे ऐप के सेव करते समय वैसी ही रखी जाती हैं। खुले टैब, आख़िरी URL और session की बाकी स्थिति यहाँ नहीं, state.json में रखी जाती है।

#टिप्पणियों के साथ उदाहरण

JSON में comments नहीं होते, इसलिए टिप्पणियाँ उदाहरण के नीचे दी गई हैं। हर field वैकल्पिक है; जो ज़रूरी नहीं, उसे छोड़ दें।

{
  "$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: URL मेन्यू के लिए review targets। प्रोजेक्ट खुलने पर पहला वाला खुलता है। id कोई भी unique string हो सकती है।
• agents.customAgents: कोई भी CLI या wrapper script। startupAgents उन agent टैब की क्रम से सूची है जो प्रोजेक्ट के साथ खुलते हैं।
• capture.sttEndpoints.compatible: कोई भी server जो OpenAI का /v1/audio/transcriptions लागू करता है (speaches, vLLM, LocalAI…)। costLimitUsd: null खर्च की सीमा बंद करता है, जो आपकी अपनी GPU के लिए ठीक रहता है। ट्रांसक्रिप्शन और खर्च देखें।
• organizer: Findings व्यवस्थित करें को सीधे किसी OpenAI-compatible /v1/chat/completions server (यहाँ Ollama) पर भेजता है। इसके बजाय अपना CLI login इस्तेमाल करने के लिए "runner": "claude-code" या "codex", और उनका मॉडल चुनने के लिए organizer.cliModels इस्तेमाल करें।
• decision: वह मॉडल जो जाँचता है कि हर finding ठीक हुआ या नहीं। Local Ollama पर Clef Flash मुफ़्त है और screenshots पढ़ता है। preset cloudflare, vercel, typesafe या custom भी हो सकता है।
• हर provider block (sttEndpoints.*, organizer.endpoints.*) timeoutMs, headers और Azure के लिए apiVersion भी लेता है।

#कोई भी provider: custom endpoints

Presets सिर्फ़ URL और मॉडल पहले से भरते हैं। हर connection (ट्रांसक्रिप्शन, Findings व्यवस्थित करना, decision model) कोई भी URL, मॉडल, headers और auth भी स्वीकार करता है, इसलिए आप कोई भी provider इस्तेमाल कर सकते हैं: Cloudflare, कोई gateway, कंपनी का proxy या आपका अपना server। नीचे के fields के नाम और बनावट तीनों में एक जैसे हैं।

ऐसे किसी भी OpenAI-compatible /v1/audio/transcriptions server के साथ ट्रांसक्रिप्शन जो अपनी key api-key header में चाहता है:

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

Cloudflare Workers AI (OpenAI-compatible chat completions) के साथ Findings व्यवस्थित करें, चाहें तो 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" } }
    }
  }
}

Cloudflare Workers AI (Clef Flash) पर, या "preset": "custom" के साथ System One API समझने वाले किसी भी server पर Decision model। Decision model endpoint में पूरा request URL लेता है ({account_id} और {model} भरे जाते हैं); बाकी हर field का नाम और बनावट ऊपर जैसी ही है:

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

CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN और बाकी variables ~/.ferret/.env में रखें। ऊपर के मॉडल नाम उदाहरण हैं। अपने provider की मॉडल सूची देखें।

#API keys

हर provider block तीन में से किसी एक तरीके से key स्वीकार करता है। जो पहले मिलता है, वही इस्तेमाल होता है:

1. "apiKey": "…": settings.json में plaintext में key। जो भी फ़ाइल पढ़ सकता है, वह key भी पढ़ सकता है, और जब तक ऐसी key मौजूद है, Settings चेतावनी दिखाता है। इससे बचें, ख़ासकर अगर फ़ाइल किसी dotfiles repo में है।
2. "apiKeyEnv": "OPENAI_API_KEY": किसी environment variable का नाम। Ferret पहले अपने environment में, फिर खुले प्रोजेक्ट के .env में, फिर ~/.ferret/.env में देखता है। Finder या Start मेन्यू से खोले गए ऐप आपकी shell profile में export किए गए variables नहीं देखते, इसलिए ~/.ferret/.env भरोसेमंद जगह है।
3. Settings में सेव की गई key: OS keychain से encrypt होकर <userData>/stt-keys.bin में (Keys कहाँ सेव होती हैं देखें)।

Ferret कोई environment variable सिर्फ़ तभी पढ़ता है जब आप उसका नाम apiKeyEnv में देते हैं। Keys कभी log नहीं होतीं, UI में कभी नहीं दिखतीं, और crash reports में कभी शामिल नहीं होतीं।

#Live reload

Ferret settings.json पर नज़र रखता है। इसके बदलने पर ऐप इसे फिर से पढ़ता है, schema से जाँचता है और लागू करता है: थीम, भाषा, layout, agents, प्रोजेक्ट और AI endpoints बिना restart के अपडेट हो जाते हैं, और Settings पेज रिफ़्रेश हो जाता है।

• अगर फ़ाइल में JSON syntax error या गलत type का कोई मान है, तो उस संपादन का कुछ भी लागू नहीं होता। ऐप आख़िरी मान्य सेटिंग्स रखता है, error को उसकी line number के साथ दिखाता है, और जब तक आप उसे ठीक नहीं करते, आपकी फ़ाइल overwrite नहीं करता।
• जब ऐप खुद सेव करता है (आपने Settings में कुछ बदला), तो वह एक अस्थायी फ़ाइल में लिखता है और उसे rename करके settings.json की जगह रख देता है, ताकि crash होने पर कभी आधी लिखी फ़ाइल न रह जाए।

#अपने coding agent से Ferret कॉन्फ़िगर करवाएँ

इसे Claude Code, Codex या फ़ाइलें संपादित कर सकने वाले किसी भी agent में paste करें:

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

यही prompt, आपके असली paths भरकर, Settings → अपने coding agent से Ferret कॉन्फ़िगर करवाएँ में Prompt कॉपी करें बटन के साथ मिलता है।