settings.yaml Reference

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

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.

An agent that matches no profile is not reviewed at all. Routing happens only through profile agents lists — an agents key inside defaults is ignored. See Profiles.

Configuration keys

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

Model and credentials

Key	Type	Default	Description
model	string	–	Model ID for the reviewer. See Supported Models.
api_key	string	–	Provider API key as ${ENV_VAR} reference. Resolved at runtime; held in process memory only.
auth_mode	string	"api_key"	"api_key" or "oauth". OAuth is supported for OpenAI only.
adversary	string	"general"	profiles only. Which built-in reviewer this profile runs. Valid values: general, code, research, prompt, spec. The profile's name is just a label and selects nothing. Setting this in defaults has no effect — see Built-in reviewers.

Reviewer behavior

Key	Type	Default	Description
system_prompt	string	-	Custom prompt for the reviewer. Use this to make the reviewer more or less strict, focus on specific concerns, or adjust its blocking behavior.
system_prompt_mode	string	"replace"	"replace": replaces the server profile's prompt entirely. "append": adds your prompt after the server profile's prompt. Only meaningful when system_prompt is set.
include_claude_md	boolean	see note	Forward your project's CLAUDE.md to the reviewer as context. Defaults to true for the main agent and false for named agents and subagents, which supply their own definition file as the reviewer's rubric. The main agent always receives CLAUDE.md — setting false for it has no effect, because CLAUDE.md is its only instruction file. Not used by Codex sessions, which take their rubric from ~/.codex/agents/<name>.toml.
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.
disable_subagents	string	"off"	Steer the agent away from spawning subagents. "off": no restriction. "system": discourage the built-in Claude Code subagents (general-purpose, Explore, Plan). "all": discourage all subagent use. Advisory guidance injected at session start, not a hard tool block.
anti_hedge	boolean	–	Push the reviewer to force real work instead of accepting its own blocks whose only remedy is to hedge, soften, or shorten the agent's output. The built-in general and code profiles enable it.

Planning gate and read guard

Key	Type	Default	Description
planning_gate	boolean	false	Hold the agent on a task until it agrees a rough approach with the reviewer. When on, the reviewer decides per prompt whether a task needs planning first. See Planning Gate.
forced_audit	boolean	false	Periodically order the reviewer to run a deliberate audit of the agent's next reviewable action, rather than relying on it to notice problems unprompted. Opt-in per profile. The reviewer issues its own determination; a refusal to audit is recorded and surfaced on the live monitor rather than silently backstopped.
read_guard_max_bytes	integer	–	Refuse unbounded reads of files larger than this many bytes; the agent is directed to sample or search instead. Unset means no ceiling.

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.plan_allowed	Tools admitted past a planning-gate hold; other tool rules (pre_review, output_visible, write_review) still apply during the hold. No effect once the gate releases.
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

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

defaults:
  model: gpt-5.4
  include_claude_md: true

profiles:
  code-review:
    agents: [coder, web-dev]
    adversary: code
    model: claude-sonnet-4-6
    tools:
      output_visible: [Read, Edit, Write]
      write_review: [Edit, Write]
  main:
    agents: [general]
    adversary: research
    model: gemini-3.1-pro-preview
    cycle:
      threshold_pct: 0.15
  data-ops:
    agents: [file-processor]
    adversary: general
    system_prompt: |
      This agent processes data files. Block any write outside of
      the data/staging/ directory. Block direct database operations.
    tools:
      review_exempt: [Read, Glob, Grep]