# bodek configuration reference

bodek (the terminal UI) keeps its own front-end settings, completely separate
from odek's server-side configuration (`~/.odek/config.json` — model, MCP,
memory, skills; see the [odek docs](https://github.com/BackendStack21/odek)).

## Settings file

Location: `~/.bodek/config.json` — override with the `BODEK_CONFIG`
environment variable. The file is optional; a missing file means "everything
defaulted". A *malformed* file is surfaced as an error at startup rather than
silently ignored.

```json
{
  "theme": "ember-dark",
  "bel": false,
  "notify": true,
  "plain": false,
  "verbosity": "quiet",
  "thinking": "medium",
  "resume": false
}
```

| Key | Type | Default | Flag | What it does |
|-----|------|---------|------|--------------|
| `theme` | string | `ember-dark` | `--theme` | Color palette: `ember-dark` · `ember-light` · `high-contrast` · `classic`. `/theme <name>` switches live **and persists it here**. |
| `bel` | bool | `true` | `--bel` | Ring the terminal bell when a turn completes or an approval is waiting (`--bel=false` mutes; the title still updates). |
| `notify` | bool | `false` | `--notify` | Raise desktop notifications (OSC 9) on turn completion and pending approvals. |
| `plain` | bool | `false` | `--plain` | Linear mode: no alt-screen; agent events print to the terminal's native scrollback (screen readers, pipes, logs). |
| `verbosity` | string | `normal` | `--verbosity` | Noise dial: `quiet` (info notes hidden), `normal`, `detailed` (`^E` expand-all view). `/verbosity` switches live **and persists it here**. An explicit `--verbosity` still wins for that launch. |
| `thinking` | string | (inherit) | `--thinking` | Reasoning depth: `disabled` · `low` · `medium` · `high`. `^T` cycles; `/thinking` opens a picker (or `/thinking <level>` sets directly) **and persist it here**. `/thinking inherit` (or `default`) clears the key so the next launch seeds from odek again. Empty inherits the odek serve default until you set a level. Requires odek ≥ v2.5.0 for string `/api/config.thinking` and inherit-on-omit. |
| `resume` | bool | `false` | `--resume` | Resume this directory's last session on start (transcript replay). Off by default: a launch starts fresh. `--new` always wins. |

Unset keys fall back to their defaults — the file only ever stores choices
you actually made (`/theme` writes `theme`, `/verbosity` writes `verbosity`,
`/thinking` writes `thinking`;
the rest you write by hand).
A leftover `"mouse"` key from older bodek builds is ignored: the
alt-screen always reports the mouse so the wheel can scroll.

## Resolution order

Every setting resolves the same way:

```
explicit flag  →  BODEK_THEME env (theme only)  →  settings file  →  built-in default
```

`/theme`, `/verbosity`, and `/thinking` persist to the settings file, so the
next launch starts where you left off unless a flag or `BODEK_THEME`
overrides them. `/thinking inherit` writes an empty value (the key is omitted).

## Environment variables

| Variable | Affects | Behavior |
|----------|---------|----------|
| `BODEK_THEME` | startup theme | Startup palette override (still beaten by an explicit `--theme`). |
| `BODEK_CONFIG` | settings path | Alternative path for the settings file (used by tests and shared-dotfile setups). |
| `NO_COLOR` | all rendering | Any non-empty value degrades the color profile to plain text in every mode — standard nocolor.org semantics. |
| `NO_MOTION` | animations | Any non-empty value replaces animated spinners/progress with single static frames. |
| `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` / `ZAI_API_KEY` / … | odek (not bodek) | Provider keys read by the `odek serve` engine bodek spawns. Set `ODEK_PROVIDER` to match. `ODEK_API_KEY` is a v1 selected-provider override only. |

## odek-side configuration

Everything the agent does is configured on the odek side
(`~/.odek/config.json` → `./odek.json` → `ODEK_*` env vars): provider, model,
provider keys, MCP servers, memory, skills, sandbox. bodek inherits it
unchanged — see the
[odek repository](https://github.com/BackendStack21/odek) for the full
server configuration reference.