Configure with settings.json

#Where the file lives

The path is the same on every OS:

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

• Set MOVIE_ADE_CONFIG_DIR to use another folder, e.g. one inside a dotfiles repo. ~ is expanded.
• Development builds (pnpm dev) use ~/.movie-ade/dev/, so hacking on MOVIE-ADE never rewrites your real settings.
• Upgrading from 0.1.0: on first launch, the old <userData>/settings.json is copied into the new files. The old file is left in place as a backup and is never modified.

In the app, Settings shows the path at the top, with Open settings.json (edits it in the built-in editor with schema completion) and Reveal in folder.

#Schema and validation

The first line of settings.json is "$schema": "./settings.schema.json". Editors such as VS Code and agents such as Claude Code use it for completion, validation and the description of every field. The schema ships inside the app and is written next to the file on every launch, so it always matches the installed version.

Keys MOVIE-ADE doesn't know are kept as they are when the app saves. Open tabs, the last URL and other session state are kept in state.json, not here.

#Annotated example

JSON has no comments, so the notes are below the example. Every field is optional; leave out what you don't need.

{
  "$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 targets for the URL menu. The first one opens when the project opens. id can be any unique string.
• agents.customAgents: any CLI or wrapper script. startupAgents lists the agent tabs opened with a project, in order.
• capture.sttEndpoints.compatible: any server that implements OpenAI's /v1/audio/transcriptions (speaches, vLLM, LocalAI…). costLimitUsd: null turns off the cost cap, which makes sense for your own GPU. See Transcription and costs.
• organizer: Organize findings sent straight to an OpenAI-compatible /v1/chat/completions server (here Ollama). Use "runner": "claude-code" or "codex" to use your own CLI login instead, and organizer.cliModels to pick their model.
• decision: the model that checks whether each finding was fixed. Clef Flash on a local Ollama is free and reads screenshots. preset can also be cloudflare, vercel, typesafe or custom.
• Every provider block (sttEndpoints.*, organizer.endpoints.*) also takes timeoutMs, headers and, for Azure, apiVersion.

#Any provider: custom endpoints

Presets only prefill the URL and model. Every connection (transcription, Organize findings, decision model) also accepts any URL, model, headers and auth, so you can use any provider: Cloudflare, a gateway, a corporate proxy or your own server. The fields below have the same names and shape in all three.

Transcription with any OpenAI-compatible /v1/audio/transcriptions server that wants its key in an 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" }
    }
  }
}

Organize findings with Cloudflare Workers AI (OpenAI-compatible chat completions), optionally through 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" } }
    }
  }
}

Decision model on Cloudflare Workers AI (Clef Flash), or with "preset": "custom" on any server that speaks the System One API. The decision model takes a full request URL in endpoint (with {account_id} and {model} filled in); every other field has the same name and shape as above:

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

Put CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN and the other variables in ~/.movie-ade/.env. The model names above are examples. Check your provider's model list.

#API keys

Each provider block accepts a key in one of three ways. The first one found wins:

1. "apiKey": "…": the key in plaintext in settings.json. Anyone who can read the file can read the key, and Settings shows a warning while one is present. Avoid it, especially if the file is in a dotfiles repo.
2. "apiKeyEnv": "OPENAI_API_KEY": the name of an environment variable. MOVIE-ADE looks in its own environment, then the open project's .env, then ~/.movie-ade/.env. Apps opened from the Finder or Start menu don't see variables exported in your shell profile, so ~/.movie-ade/.env is the reliable place.
3. The key saved in Settings: encrypted with the OS keychain in <userData>/stt-keys.bin (see Where keys are stored).

MOVIE-ADE reads an environment variable only when you name it in apiKeyEnv. Keys are never logged, never shown in the UI, and never included in crash reports.

#Live reload

MOVIE-ADE watches settings.json. When it changes, the app re-reads it, checks it against the schema and applies it: theme, language, layout, agents, projects and AI endpoints update without a restart, and the Settings page refreshes.

• If the file has a JSON syntax error or a value of the wrong type, nothing from that edit is applied. The app keeps the last valid settings, shows the error with its line number, and doesn't overwrite your file until you fix it.
• When the app itself saves (you changed something in Settings), it writes to a temporary file and renames it over settings.json, so a crash never leaves a half-written file.

#Let your coding agent configure MOVIE-ADE

Paste this into Claude Code, Codex or any agent that can edit files:

Edit ~/.movie-ade/settings.json following the JSON Schema in
~/.movie-ade/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 ~/.movie-ade/.env.
MOVIE-ADE 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">

The same prompt, with your actual paths filled in, is under Settings → Let your coding agent configure MOVIE-ADE with a Copy prompt button.