settings.yaml Reference¶

Complete reference for ~/.zwischen/settings.yaml. All keys are optional unless noted.

`env`¶

Environment variables injected at startup. Real environment variables take precedence.

Key	Required	Description
`ZWISCHEN_API_KEY`	Yes	Your Zwischen API key
`OPENAI_API_KEY`	No	OpenAI provider key
`ANTHROPIC_API_KEY`	No	Anthropic provider key
`GEMINI_API_KEY`	No	Google provider key
`DEEPSEEK_API_KEY`	No	DeepSeek provider key

`projects`¶

List of per-directory enable/disable rules. Evaluated in order; longest matching path wins. If omitted, Zwischen is enabled everywhere.

Key	Type	Description
`path`	string	Directory path (tilde-expanded)
`enabled`	boolean	Whether Zwischen monitors sessions in this directory

`defaults`¶

Baseline configuration for all reviewed agents. Accepts all keys listed below.

`profiles`¶

Named entries that deep-merge on top of defaults for specific agents. Each profile accepts all keys listed below, plus a required agents list.

Key	Type	Description
`agents`	list of strings	Agent names this profile matches. Required for the profile to activate. First match wins.

Configuration keys¶

These keys are valid in both defaults and individual profiles entries.

Model and credentials¶

Key	Type	Default	Description
`model`	string	—	Model ID for the reviewer. See Supported Models.
`api_key`	string	—	Provider API key. Held in process memory only.
`auth_mode`	string	`"api_key"`	`"api_key"` or `"oauth"`. OAuth is supported for OpenAI only.
`profile_id`	string	`"general"`	Which server-side adversary profile to use.

Reviewer behavior¶

Key	Type	Default	Description
`system_prompt`	string	—	Custom system prompt for the reviewer.
`system_prompt_mode`	string	`"replace"`	`"replace"`: replaces the server profile's prompt. `"append"`: appends to it. Only meaningful when `system_prompt` is set.
`include_claude_md`	boolean	`true`	Forward your project's CLAUDE.md to the reviewer as context.
`web_search`	boolean	`false`	Allow the reviewer to use web search during review.
`model_tuning`	boolean	`true`	Apply provider-specific and model-specific prompt adjustments from Zwischen Labs.
`scrutiny_level`	integer	Server default	Initial scrutiny level for the reviewer (1–5). Can be changed mid-session with `/z level`.

Tool visibility and enforcement¶

Nested under the tools key. All sub-keys accept a list of tool names.

Key	Description
`tools.output_visible`	Tools whose full output the reviewer can see during live review.
`tools.pre_review`	Tools reviewed before execution. Reviewer can block the call before it runs.
`tools.write_review`	Like `pre_review`, but specialized for Edit/Write — reviewer sees the proposed diff.
`tools.whitelisted`	Tools passed through without blocking, still streamed as context. Available during blocks.
`tools.review_exempt`	Tools invisible to the reviewer — no streaming, no enforcement.

Context cycling¶

Nested under the cycle key.

Key	Type	Description
`cycle.threshold_pct`	float	Fraction of context window usage that triggers a cycle (e.g., `0.15`).
`cycle.tail_depth`	integer	Number of recent messages carried over after a cycle.

Full example¶

env:
  ZWISCHEN_API_KEY: "your-key-here"

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

defaults:
  model: gpt-5.4
  api_key: your-provider-key
  profile_id: general
  include_claude_md: true

profiles:
  code-review:
    agents: [coder, web-dev]
    model: claude-sonnet-4-6
    tools:
      output_visible: [Read, Edit, Write]
      write_review: [Edit, Write]
  research:
    agents: [orchestrator]
    model: gemini-2.5-pro
    cycle:
      threshold_pct: 0.15
  bulk-processing:
    agents: [file-processor]
    tools:
      review_exempt: [Read, Glob, Grep]