settings.json

Everything on the Settings page is backed by a real, hand-editable settings.json. That’s VS Code’s model, and for the same reason: a flat file of dotted keys is unambiguous to edit, readable in a diff, and easy to copy between machines.

It also carries a few things the UI has no control for, like per-token theme colours.

Opening it

• Command palette (⌘⇧P) → Preferences: Open Settings (JSON), which opens the file in Bandura’s own editor.
• Settings → settings.json → Edit settings.json opens the same editor.
• Settings → settings.json → Show in folder reveals the file in Finder/Explorer, if you’d rather use your own editor.

The file lives in the app’s user-data directory. Changes apply live. Save, and the app picks them up, whether you saved from Bandura or from another editor. Bandura watches the file; there is no reload command and no restart.

“Live” means all of it, not just the chrome: a colour change repaints the app, the code editor, and the terminal at the same moment. Nothing needs to be closed and reopened to pick up a new palette.

What’s not in it

Your API keys and your licence key are deliberately not in this file.

• API keys live in your operating system’s encrypted store (Keychain on macOS, DPAPI on Windows, libsecret on Linux), one per provider (see Connect an AI provider).
• Your licence key lives in the app’s own config file, not here. It isn’t encrypted and isn’t meant to be: a licence key has to stay portable, re-enterable on a new machine, quotable in a support email. Keeping it out of settings.json just means a hand-edit can’t invalidate it.

So settings.json is safe to read over someone’s shoulder, paste into a bug report, or sync between machines. No API key is in it.

Where every other piece of state lives, and what does or doesn’t cross the network, is on the security page.

The keys

Every key is listed here. Delete one and it returns to its default.

Appearance

Notifications

Editor

These drive the code editor, and most are named after the Monaco option they set, so the mapping needs no lookup table.

AI

The first three are also editable from Settings → AI, which is the easier route because it stores the API key alongside them. See Connect an AI provider.

How it behaves when you get it wrong

The file is yours, so Bandura reads it defensively rather than rewriting it:

• Comments are allowed. // and /* … */ both work, and the generated file uses them to document every key inline. A // inside a string survives, so a base URL like "http://localhost:11434/v1" is not half a comment. Trailing commas are not allowed, though: comments are the one extension to strict JSON here.
• Delete a key to restore its default. There’s no “reset” to hunt for; an absent key is the default.
• An invalid value degrades to its default, never a crash and never a silent rewrite of your file. What you see is the setting snapping back to the default; the offending line stays in your file, exactly as you typed it. A number outside its range is clamped to the nearest legal value instead, because 21 when the max is 20 is a preference and 200 is a typo.
• A key Bandura doesn’t recognize is kept, not deleted. A typo stays visible, and a setting from a newer version survives a downgrade. Should the app ever rewrite the file itself, those keys are re-emitted verbatim under a comment saying so.
• One bad entry in ui.themeOverrides is dropped on its own, so a single typo doesn’t discard a hand-tuned palette.

If the file doesn’t parse at all

A JSON syntax error is a different case from a bad value, and it’s handled conservatively:

• The app runs on defaults until it parses again. It doesn’t refuse to start, and it doesn’t “fix” the file for you.
• Your file is not touched. In the rare case where Bandura itself has to write settings while the on-disk copy is unparseable, it first copies it to settings.json.bak, so the version you were mid-way through editing is still there.
• Saving from inside Bandura validates first. Edit settings.json refuses to write text that isn’t valid JSONC and shows the parse error inline, so the editor can’t be the thing that breaks the file. It also warns if the file changed on disk since you opened it.
• Every write is atomic (written to a temporary file and renamed into place), so an interrupted save can’t leave a half-written settings.json.

Theme overrides

ui.themeOverrides maps colour token names to colours, applied on top of whichever theme ui.theme selects:

{
  "ui.theme": "dark",
  "ui.themeOverrides": {
    "bg": "#101010",
    "node-request": "#7aa2f7"
  }
}

Values must be hex, rgb(), or hsl(). Those go straight into CSS custom properties, the code editor’s theme, and the terminal palette, so anything more exotic would break one of the three. There are 22 token names; anything else is ignored, and so is a value that isn’t a colour. In both cases only that one entry is dropped, not the whole object.

Note the asymmetry with ui.accent directly above it: the accent is hex-or-preset only. Its hover shade and the text colour on filled accent surfaces are computed from the colour’s channels, which needs hex.

The full token list, what each one paints, and a worked example are on Customize the theme.

Example

{
  // A local model, no key, nothing leaves the machine.
  "ai.provider": "openai-compatible",
  "ai.baseUrl": "http://localhost:11434/v1",
  "ai.model": "llama3.1",

  "ui.theme": "light",
  "ui.accent": "#ff7a59",
  "ui.density": "compact"
}

Every other key falls back to its default because it isn’t there.

Related: Settings & appearance · Customize the theme