Skip to content

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 API key:

Verify that ZWISCHEN_API_KEY is set in your environment. Run zwischen auth if it isn't – the wizard persists it as an OS environment variable.

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

Send a directive to adjust behavior for the current session:

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

If the reviewer is consistently too aggressive, use system_prompt in your settings file to set expectations, or switch to a lighter profile with /z adversary.

The reviewer never blocks anything

Check your tool visibility configuration - tools in review_exempt are invisible to the reviewer, and tools in whitelisted are never blocked. See Tool Visibility. You can also use system_prompt in your settings to raise expectations, or switch to a stricter profile with /z adversary.

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:

  1. Check the reviewer's reasoning with /z spy
  2. Send a directive: /z direct Release the block and let the agent proceed.
  3. Clear the block directly: /z unblock (supervision continues)
  4. If the issue is systemic, adjust your tool visibility or profile configuration

If message_adversary is unavailable (MCP error, lost session ID), use /z unblock --all to clear all blocks across all sessions.

"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:

export ZWISCHEN_DAEMON_PORT=8390