Troubleshooting

From docs.md §25. Report new issues on GitHub.

`zox: command not found` after `bun add -g zox-code`

Ensure Bun’s global bin directory is on your PATH (bun pm bin -g). Or skip a global install: bunx zox-code ….

You are on mock/echo. Set a provider key and --model. See Models and BYOK.

Default worktree. Open .zox/worktrees/... or restart with --sandbox host. See Sandbox.

Approve in TUI, or SDK respondPermission. --auto-approve for tools only. Headless eval will not approve prompt-level ask. See Permissions.

Need --token or ZOXX_SERVER_TOKEN. Server must still be running (zox serve). See Server, OpenAPI, and SDK.

Trust the project: zox hooks trust. Check .zox/hooks.json schema. Command hooks must print JSON. See Hooks.

judge.enabled is false by default. If enabled but you see skip warnings, the API key or network failed (fail-open). See Prompt guardrail.

Server process must have the command on PATH (bunx, npx, binaries). Env interpolation only fills ${VAR} from the environment. See MCP.

Can happen with extra roots (for example leftover .zox/worktrees). Lint the packages you care about or clean worktrees.

Always bun install after pulling so workspace packages like @zox/judge link.

Redaction is best-effort. Set observability.recordContent: false. Do not commit .env or paste keys into /remember. See Observability.