Skip to content

Common Issues

Two commands help diagnose most of these quickly:

  • /z status shows the reviewer's current model and profile.
  • /z monitor opens a live window streaming the reviewer's verdicts, so you can watch blocks and reasoning as they happen.

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. Watch the reviewer's reasoning with /z monitor
  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.

The agent is held before it starts a task

If the agent pauses before doing any real work and says it's plan-gated, the planning gate is holding it – either because planning_gate is set for the profile or because you ran /z plan. The agent is meant to send the reviewer a rough plan via message_adversary; the reviewer releases it once the direction is sound. To clear the hold without going through a plan, run /z unblock.

The agent won't read a whole file

If the agent refuses to read a large file and reads a bounded slice or searches it instead, the read guard is refusing an oversized unbounded read. Adjust or remove the read_guard_max_bytes setting to allow whole-file reads.

"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 from a terminal:

zwischen auth --provider openai

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