# Settings

Every persistent setting, changeable mid-session.

Type `/settings` to open a dialog with every persistent setting. Changes are written to `$ZOT_HOME/config.json` without requiring a restart. Rendering toggles apply immediately; settings that affect model requests apply to subsequent turns. Rows that open a sub-view (like model shortcuts) use `esc` to go back one level before it closes the dialog.

## Configuration files

zot stores both configuration and runtime state under `$ZOT_HOME`, even when that directory is under the platform's state directory. You can edit these files directly while zot is not running:

- `config.json` selects the default `provider` and `model` and stores UI preferences. Interactive settings and model selections also update it. Explicit `--provider` and `--model` flags override the saved selection for a run.
- `models.json` optionally defines model metadata and provider endpoints (`baseUrl`). Registering a model does not select it as the default.
- `auth.json` stores credentials. Prefer `/login` for supported providers, and keep secrets out of the other two files.

Neither `config.json` nor `models.json` is required when starting zot with an explicit provider and model. Without a saved or explicit provider, zot defaults to Anthropic and may offer login if no usable credentials are available. Local Ollama does not need login.

For example, create this minimal configuration, or merge these fields into your existing file, to select a local Ollama model by default:

```json title="$ZOT_HOME/config.json"
{
  "provider": "ollama",
  "model": "qwen3.5:4b"
}
```

The Ollama server must already be running and have that model installed. See `Models` for local, remote, and two-host setup examples. `baseUrl` belongs in `models.json`, not `config.json`.

## Codemode configuration

The optional [Codemode](/docs/codemode) tool is configured through CLI flags or the `codemode` object in `$ZOT_HOME/config.json`, not an interactive settings toggle. Merge this object into your configuration to enable script-only client tool presentation:

```json
{
  "codemode": {
    "enabled": true,
    "mode": "only",
    "inlineBudget": 3000
  }
}
```

`mode` accepts `on` (keep direct tool definitions) and `only` (expose client tools through scripts). `inlineBudget` is a non-negative estimated token budget for tool declarations, defaulting to 3000. Zero keeps discovery without inline declarations. `--codemode` and `--codemode-only` override the saved mode for a run. `--no-tools` takes precedence.

## Chat timestamps

Open `/settings`, choose **timestamps**, then configure:

| Control | Options and default |
| --- | --- |
| enabled | On or off. Off by default. Stored as `chat_timestamps`. |
| interval | Every message (0, the default), 1, 5, 10, 15, 30, or 60 minutes. Stored as `chat_timestamp_interval_minutes`. |
| date display | **Start of each day** (default) or **Every timestamp**. Stored as `chat_timestamp_date` with values `day_start` or `every_message`. |

Timestamps use muted text on existing separator rows, aligned with the tool box's right edge and leaving the same two-column right margin. They use the local timezone. **Start of each day** shows `YYYY-MM-DD HH:MM` on the first timestamp and when the day changes, then just `HH:MM` for subsequent timestamps that day. **Every timestamp** always includes the date.

An interval of 0 shows every eligible message. A positive interval selects a timestamp once at least that many minutes have elapsed since the last selected timestamp, not since the previous message. The first eligible message and day changes always qualify. Date display does not change interval selection.

For example, enable timestamps on every eligible message with the date always visible by merging these fields into your configuration:

```json title="$ZOT_HOME/config.json"
{
  "chat_timestamps": true,
  "chat_timestamp_interval_minutes": 0,
  "chat_timestamp_date": "every_message"
}
```

You can set any nonnegative integer interval directly in `config.json`. Missing or negative intervals use 0, and explicitly saved intervals are preserved. Missing or unknown date modes use `day_start`. Changes through `/settings` apply immediately and persist across restarts. Press `esc` to return from the timestamps sub-view to settings.

User messages, completed assistant messages, and tool results are eligible. Missing timestamps and compaction summaries are skipped, and labels that do not fit in a narrow terminal are omitted. Saved session timestamps are reused on resume. These controls affect only the interactive display, not model input or print, JSON, or RPC output.

> **Streaming limitation**
>
> Timestamps appear after messages complete, not during streaming. They do not mark unread portions of a long response.

## Interactive settings

| Setting | What it controls |
| --- | --- |
| render images | Draw images returned by read inline using the terminal's image protocol (Ghostty, Kitty, iTerm2, WezTerm). Auto-detected from TERM_PROGRAM; the toggle overrides detection. Greyed out and forced off on terminals that speak no image protocol. |
| auto-swarm | Let the main agent spawn background sub-agents in parallel via swarm_spawn. |
| auto-compact threshold | Choose when interactive sessions automatically condense conversation history: off, 70%, 80%, 85% (default), or 90% of the model's advertised context window. The choice takes effect without restarting and is stored as auto_compact_threshold. Off disables percentage-based triggers, but manual /compact and automatic recovery from payload-too-large responses remain available. |
| jail new sessions by default | Start interactive, print, JSON, RPC, and background-agent runs with tools confined to the working directory. Off by default. Changing it updates the current sandbox immediately; /jail and /unjail only override the current session. Stored as jail_by_default. |
| PowerShell tool (Windows only) | Enable or disable native PowerShell alongside the default tools. Off by default; stored as `powershell_enabled`. Updates the live tool list without restarting and applies to future Windows runs in other modes too. Explicit `--tools` or `--no-tools` overrides the preference and disables the toggle for that run. Execution remains blocked while jailed and subject to packaged-agent permissions. See [Tools](/docs/tools). |
| OpenRouter Server Tools | Opt in to OpenRouter's remote web search, web fetch, advisor, subagent, fusion, image generation, datetime, and model-search tools. Off by default and available only with the OpenRouter provider. zot allows at most four remote server-tool calls per turn. --no-tools disables them, and preset-owned tools are not overridden. These tools run without zot's local confirmation dialog and may incur additional OpenRouter charges. Stored as openrouter_server_tools_enabled. |
| fuzzy skill suggestions (upcoming) | Use relevance-ranked, case-insensitive subsequence matching for `/skill:` names, with alphabetical tie-breaking and matching characters in bold. Empty queries remain alphabetical; exact names retain priority. Off by default; missing or `false` preserves prefix matching. Applies immediately and is stored as `fuzzy_skill_suggest`. Other slash commands and invocation lookup are unchanged. See [Skills](/docs/skills). |
| compact transcript rendering | Render tool calls without borders and sent messages without padded bubbles. Off by default. Applies immediately and is stored as `compact_mode`. |
| collapse tool call rendering | Retain tool headers, the final rendered preview line, and an explicit error indicator for failed calls. Hide the rest of the body while preserving boxed, flat, or compact layouts. Press `ctrl+o` to expand the full output. Off by default. Applies immediately and is stored as `collapse_tool_call`. See [Tools](/docs/tools). |
| timestamps | Sub-view with an enabled toggle, interval selector, and date display options. Off by default. See Chat timestamps above. |
| show loaded resources at startup | List loaded AGENTS.md paths, extensions, and user-installed skills in compact `Context`, [Extensions](/docs/extensions), and [Skills](/docs/skills) sections above the transcript. Built-in skills are omitted. Off by default. The lists are display-only and are not sent to the model or stored in the session transcript. Stored as `show_instructions_at_startup`. |
| tui settings | Sub-view for click-to-position and persistent text selection (off by default), input style, status position, and working spinner position. Mouse interaction is stored as `tui_click_to_position`. See [TUI settings](/docs/tui-settings). |
| reasoning level | Reasoning depth for the active model. Use /reasoning to open this selector directly. It only shows distinct levels supported by the model; models without reasoning support only offer off. Also settable per run with --reasoning. |
| color theme | auto/dark/light or any JSON theme from $ZOT_HOME/themes or a loaded extension. |
| model shortcuts | Sub-view with nine slots (model 1 ... model 9). Press enter on a slot to open the /model selector and bind a provider/model, backspace to clear it. Then Ctrl+1 ... Ctrl+9 from the editor instantly switch the active model (same cross-provider swap as /model, transcript and cost carried over). No-op while a turn is running. |