canonical product diagnostics / stable remediation anchors

Doctor guide

Run the product doctor in the same terminal where Codex or Claude Code will run. Every WDOJO_* result links to a stable anchor on this page; diagnostics are designed to be reviewed before sharing.

Start in the product terminal.

waitdojo doctor --product
waitdojo doctor --product --json

The human view gives direct fixes. JSON adds stable IDs, WDOJO_* codes, redacted evidence, blockers, and the same documentation URLs. It does not include prompts, code, full home paths, tokens, or tool output.

Supported platform.

WaitDojo v1 runs on macOS, Linux, and Windows through WSL2. Native Windows is not a supported runtime because WaitDojo and the coding agent must share the same Unix environment and tmux session.

Windows and WSL2.

Open an Ubuntu WSL2 distribution, install WaitDojo and the coding agent inside that distribution, then rerun the doctor there.

wsl --status
wsl -l -v

If WSL metadata times out, run wsl --shutdown, reopen the distribution, and retry. If no distribution appears, install or repair Ubuntu before continuing.

tmux 3.2+ and Linux prerequisites.

WaitDojo uses tmux to keep the coding agent above the sidecar and to resize the sidecar when the agent state changes. Codex on Linux also needs Bubblewrap.

# Ubuntu / WSL2 with Codex
sudo apt update && sudo apt install -y tmux bubblewrap

# macOS
brew install tmux

Coding-agent command.

Install the official codex or claude command in the same environment as WaitDojo. A Windows-host agent cannot deliver hooks to a WaitDojo process running inside WSL2.

Stable install path.

The reviewed installer places the binary at ~/.local/bin/waitdojo. If the doctor reports a development, temporary, or missing executable, reinstall the release and run the doctor from that installed binary.

Passive hook setup.

waitdojo init codex
# or
waitdojo init claude

Existing hook settings are preserved and backed up. WaitDojo records only a timestamp and configured lifecycle event name; it does not parse or store hook stdin, prompts, code, transcript paths, tool input, or tool output.

Terminal geometry.

Use at least 80 columns by 22 rows. An 80×30 or larger terminal gives drills their full-height layout. Rerun the doctor inside an interactive terminal if geometry could not be verified.

Local paths and permissions.

WaitDojo keeps its stats, lifecycle event rows, configuration, backups, local telemetry queue, and support bundles below ~/.codex/waitdojo/ by default. Set WAITDOJO_DATA_DIR only when that location is not writable.

Optional and development-only checks.

Live Lichess configuration and fake tmux E2E checks are not required for the core recommendation → drill → result → return loop. The product remains usable when optional integrations are not configured.