設定

settings.json で設定する

Ferret の設定はすべて1つの JSON ファイルにあり、隣に JSON Schema が置かれています。そのため、自分で、またはコーディングエージェント（たとえば Claude Code、Codex、Gemini CLI）にファイルを編集させて、アプリを設定できます。変更はアプリの起動中に反映されます。

#ファイルの場所

パスはどの 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 リポジトリの中）を使うには FERRET_CONFIG_DIR を設定します（以前の名前 MOVIE_ADE_CONFIG_DIR も使えます）。~ は展開されます。
開発用のビルド（pnpm dev）は ~/.ferret/dev/ を使うので、Ferret 自体を開発しても普段の設定は書き換わりません。
0.1.0 からの更新: 初回の起動で、以前の <userData>/settings.json を新しいファイルにコピーします。古いファイルはバックアップとしてそのまま残し、変更しません。

MOVIE-ADE からの更新: 初回の起動で、settings.json、state.json、usage/、.env を ~/.movie-ade/ から ~/.ferret/ にコピーします。古いフォルダはそのまま残し、変更しません。

アプリの設定では、上部にパスが表示され、settings.json を開く（スキーマの補完つきで内蔵エディタで編集）とフォルダで表示があります。

#スキーマと検証

settings.json の最初の行は "$schema": "./settings.schema.json" です。VS Code などのエディタや Claude Code などのエージェントは、これを使って補完・検証し、各項目の説明を表示します。スキーマはアプリに同梱され、起動のたびにファイルの隣へ書き出されるので、常にインストールしているバージョンと一致します。

Ferret が知らないキーは、アプリが保存するときもそのまま残します。開いているタブや最後の URL などのセッションの状態は、ここではなく state.json に保存します。

#注釈つきの例

JSON にはコメントが書けないので、説明は例の下に置きます。どの項目も省略でき、要らないものは書かなくてかまいません。

{
  "$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 メニューに出るレビュー対象。プロジェクトを開くと最初のものが開きます。id は重複しなければどんな文字列でもかまいません。
agents.customAgents: 任意の CLI やラッパースクリプト。startupAgents は、プロジェクトと一緒に開くエージェントのタブを順に並べたものです。
capture.sttEndpoints.compatible: OpenAI の /v1/audio/transcriptions を実装したサーバーならどれでも使えます（speaches、vLLM、LocalAI…）。costLimitUsd: null で費用の上限を外します。自前の GPU ならこれが妥当です。文字起こしと費用を見てください。
organizer: 指摘を整理を OpenAI 互換の /v1/chat/completions サーバー（ここでは Ollama）に直接送ります。代わりに自分の CLI のログインを使うなら "runner": "claude-code" か "codex" にし、そのモデルは organizer.cliModels で選びます。
decision: 各指摘が直ったかを判定するモデル。ローカルの Ollama で動く Clef Flash は無料で、スクリーンショットも読めます。preset には cloudflare、vercel、typesafe、custom も指定できます。
どの接続先のブロック（sttEndpoints.*、organizer.endpoints.*）も、timeoutMs、headers、Azure なら apiVersion を受け付けます。

Ferret があなたの代わりに AI の費用を払うことはありません。組み込みのキーも中継サーバーも無く、すべてのリクエストはあなたのマシンから、あなたが設定した接続先へ、あなたのキーで送られます。

#どのプロバイダでも: カスタムの接続先

プリセットは URL とモデルを埋めるだけです。どの接続（文字起こし、指摘を整理、判定モデル）も任意の URL、モデル、ヘッダー、認証を受け付けるので、Cloudflare、ゲートウェイ、社内のプロキシ、自前のサーバーなど、どのプロバイダでも使えます。下の項目は3つとも同じ名前・同じ形です。

項目	意味
`baseUrl`, `model`	任意の http(s) の URL とモデル名。URL の中の `{account_id}` は `accountId`、または環境変数 `CLOUDFLARE_ACCOUNT_ID` に置き換わります
`authScheme`	`bearer`（`Authorization: Bearer <key>`）、`header`（`authHeader` で指定した名前のヘッダーにキーを入れる）、`none` のどれか。省略するとプロバイダの既定のままです
`headers`	追加のヘッダー。値はただの文字列か、環境変数から読む `{"env": "VAR"}`（`apiKeyEnv` と同じ順で探します）。`Authorization` やゲートウェイのトークンのような秘密のヘッダーは `{"env": …}` の形でしか受け付けません。設定画面では `Name: ${VAR}` と書きます
`apiKey` / `apiKeyEnv`	キー。API キーを参照

キーを api-key ヘッダーで受け取る、OpenAI 互換の /v1/audio/transcriptions サーバーで文字起こしする例:

"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 互換の chat completions）で指摘を整理する例。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 を話すどのサーバーでも使えます。判定モデルは endpoint にリクエスト先の完全な URL を取ります（{account_id} と {model} は埋められます）。ほかの項目は上と同じ名前・同じ形です:

"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 などの変数は ~/.ferret/.env に書きます。上のモデル名は例です。プロバイダのモデル一覧を確かめてください。

#API キー

どの接続先のブロックも、キーを次の3通りのどれかで受け付けます。最初に見つかったものが使われます。

"apiKey": "…": settings.json に平文で書いたキー。ファイルを読める人はキーも読め、キーがある間は設定に警告が出ます。特にファイルを dotfiles リポジトリに置いているなら避けてください。
"apiKeyEnv": "OPENAI_API_KEY": 環境変数の名前。Ferret は自分の環境、開いているプロジェクトの .env、~/.ferret/.env の順に探します。Finder やスタートメニューから開いたアプリには、シェルのプロファイルで export した変数が見えないので、~/.ferret/.env に置くのが確実です。
設定で保存したキー: OS のキーチェーンで暗号化して <userData>/stt-keys.bin に保存します（キーの保存場所を参照）。

Ferret が環境変数を読むのは、apiKeyEnv にその名前を書いたときだけです。キーをログに残したり、画面に表示したり、クラッシュレポートに含めたりすることはありません。

#編集するとすぐ反映

settings.json を編集すると、起動中のアプリにそのまま反映される。

Ferret は settings.json を見張っています。変わると読み直し、スキーマで確かめてから反映します。配色、言語、レイアウト、エージェント、プロジェクト、AI の接続先は再起動なしで更新され、設定画面も更新されます。

ファイルに JSON の構文エラーや型の違う値があると、その編集は何も反映しません。アプリは直前の正しい設定のまま動き、エラーを行番号つきで表示し、直すまでファイルを上書きしません。
アプリ自身が保存するとき（設定で何かを変えたとき）は、一時ファイルに書いてから settings.json へ名前を変えて置き換えるので、途中で落ちても書きかけのファイルは残りません。

#コーディングエージェントに Ferret を設定させる

次の文を Claude Code、Codex など、ファイルを編集できるエージェントに貼り付けます。

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

同じプロンプトが、実際のパスを埋めた形で設定 → コーディングエージェントに設定させるにあり、プロンプトをコピーボタンでコピーできます。

GitHub でこのページの翻訳を手伝う（新しいタブで開きます）