Troubleshooting

Doctor command

The doctor command runs automated diagnostics across six categories: binary availability, hook registration, config validity, backup health, tool dependencies, and XDG directory layout.

# Run all diagnostic checks
klaudiush doctor

# Detailed output
klaudiush doctor --verbose

# Auto-fix detected issues
klaudiush doctor --fix

# Check specific category
klaudiush doctor --category config
klaudiush doctor --category hook
klaudiush doctor --category backup
klaudiush doctor --category xdg      # XDG directory layout and migration status

The --fix flag attempts to automatically resolve detected issues. It creates backups before making any changes.

Common issues

klaudiush not running on tool calls

Check that the hook is registered in ~/.claude/settings.json and that the klaudiush binary is on your PATH.

# Verify hook is registered
cat ~/.claude/settings.json | jq '.hooks'

# Test hook manually
echo '{"tool_name":"Bash","command":"git status"}' | klaudiush --hook-type PreToolUse

Validator not triggering

Verify the validator is enabled in your config. Use debug config to see the loaded configuration and check the enabled flag.

# See what config is loaded
klaudiush debug config

# Check specific validator
klaudiush debug config --validator git.commit

# View active rules
klaudiush debug rules

Config not loading

Common causes: TOML syntax errors, wrong field names, invalid duration format (use "10s" not 10). Run klaudiush debug config to see parsing errors.

File validators timing out

File validators (markdown, shellscript, terraform) run external tools. If these tools are slow or missing, the validator can time out. Check that the tools are installed and increase the timeout in your config if needed.

Crash dumps

klaudiush has automatic panic recovery. If the dispatcher crashes, it writes a dump to $XDG_DATA_HOME/klaudiush/crash_dumps/ (default ~/.local/share/klaudiush/crash_dumps/) and exits with code 3 (so Claude Code allows the operation through).

# List crash dumps
klaudiush debug crash list

# View a specific crash dump
klaudiush debug crash view <id>

# Clean old crash dumps
klaudiush debug crash clean

Debug logging

Enable debug or trace logging to see what klaudiush is doing. Logs are written to $XDG_STATE_HOME/klaudiush/dispatcher.log (default ~/.local/state/klaudiush/dispatcher.log). Set the KLAUDIUSH_LOG_FILE environment variable to write logs to a custom path instead. The old symlink at ~/.claude/hooks/dispatcher.log still works after migration.

# Enable debug logging
klaudiush --debug --hook-type PreToolUse

# Enable trace logging (verbose)
klaudiush --trace --hook-type PreToolUse

# View logs (default XDG path)
tail -f ~/.local/state/klaudiush/dispatcher.log

# Or use a custom log path
KLAUDIUSH_LOG_FILE=/tmp/klaudiush.log klaudiush --debug --hook-type PreToolUse