Common Issues¶

Zwischen doesn't attach when I start Claude Code¶

Check the installation:

zwischen install --dry-run

If this shows changes that need to be made, run zwischen install --update to re-wire the hooks.

Check your settings file:

Verify ~/.zwischen/settings.yaml exists and contains a valid ZWISCHEN_API_KEY in the env block.

Check project rules:

If you have a projects block in your settings, make sure the current directory isn't disabled. See Project Rules.

The reviewer blocks everything¶

Lower the scrutiny level:

/z level 2

Or send a directive:

/z direct Be less aggressive. Only block truly dangerous operations.

If the reviewer is consistently too aggressive, consider lowering scrutiny_level in your settings file.

The reviewer never blocks anything¶

Raise the scrutiny level:

/z level 4

Also check your tool visibility configuration — tools in review_exempt are invisible to the reviewer, and tools in whitelisted are never blocked. See Tool Visibility.

The agent is stuck in a block loop¶

The agent can dispute blocks by calling message_adversary. If the agent keeps getting blocked on the same issue:

Check the reviewer's reasoning with /z spy
Send a directive: /z direct Release the block and let the agent proceed.
If the issue is systemic, adjust your tool visibility or profile configuration

"No adversary session found" error¶

This means the message_adversary MCP tool can't find the reviewer session. Possible causes:

The daemon isn't running — try /z restart
Supervision is disabled — try /z enable
The session ID is wrong — this usually indicates a wiring issue; try zwischen install --update

The reviewer seems confused or stale¶

The reviewer's context window may be full. Reset it:

/z cycle

This triggers a handoff and starts a fresh reviewer context. See Context Cycling.

OAuth errors (OpenAI)¶

Re-authenticate:

zwischen oauth

Or from inside Claude Code:

/z oauth

Make sure auth_mode: oauth is set in your settings file if you're using OAuth instead of API key auth.

Daemon port conflict¶

The daemon runs on localhost:8384 by default. If another process is using that port, set ZWISCHEN_DAEMON_PORT in your environment or in the env block of your settings file:

env:
  ZWISCHEN_DAEMON_PORT: "8390"