Skip to content

Settings File

Zwischen reads all configuration from ~/.zwischen/settings.yaml. This file is created by the install wizard and can be edited directly at any time. Settings are re-read on every session start, so changes take effect immediately without restarting the daemon.

Editing it

You can edit the YAML by hand, or use the interactive editor:

zwischen config      # from a terminal

/z config            # from inside a session

The editor opens in its own window. Pick a scope – defaults, a named profile, global settings, or credentials – and change settings from menus, with each profile showing what its unset keys inherit from defaults.

A scope shows only what it overrides

Opening a profile lists just the settings that profile currently sets. Every other setting – model and adversary included – is under + Add or change a setting. A profile with no Model row is inheriting one, not prevented from having its own.

The rest of this page describes the file itself, which is worth understanding whichever way you edit it.

Structure

The settings file has three top-level blocks:

projects:
  - path: ~/work/sensitive-repo
    enabled: false
  - path: ~/work
    enabled: true

defaults:
  model: gpt-5.4

profiles:
  code-review:
    agents: [coder, web-dev]
    model: claude-sonnet-4-6

projects

Per-directory enable/disable rules. See Project Rules.

defaults

Baseline configuration for all reviewed agents. See the sections below for all available keys.

profiles

Named configuration overrides for specific agents. See Profiles.

Settings resolution

Settings resolve in order, with each layer deep-merging on top of the previous:

  1. Server defaults – built into the Zwischen server
  2. defaults – your baseline configuration
  3. First matching profile – overrides for specific agents

A profile match is what starts a reviewer

defaults alone does not get an agent reviewed. An agent that matches no profile's agents list runs unmonitored. See Profiles.

For nested dicts like cycle and tools, the merge is key-by-key. A profile that sets tools.output_visible doesn't erase your defaults.tools.pre_review – both are preserved.

Exception: system_prompt and system_prompt_mode do not deep-merge. A profile's system_prompt is used as-is – it does not inherit from or append to defaults.system_prompt.

Minimal example

The smallest configuration that actually reviews something:

defaults:
  model: gpt-5.4

profiles:
  main:
    agents: [general]
    adversary: general

defaults sets GPT-5.4 as the reviewer model, and the main profile is what routes your main agent to a reviewer. Without that profile, nothing is monitored. API keys (ZWISCHEN_API_KEY and provider keys like OPENAI_API_KEY) are OS environment variables managed by zwischen auth – they are not stored in this file.

Next steps