FAQ

General

Do I need a config file?

No. All validators have good defaults. A config file is only needed when you want to change defaults, add custom rules, or configure features like backup and exceptions.

What happens when klaudiush crashes?

klaudiush has automatic panic recovery. If it crashes, it writes a crash dump to $XDG_DATA_HOME/klaudiush/crash_dumps/ (default ~/.local/share/klaudiush/crash_dumps/), exits with code 3, and Claude Code allows the operation through. Your workflow is never blocked by a klaudiush crash.

How fast is klaudiush?

Config loading takes under 45 microseconds. Individual validators run in under 50ms. The full validation chain typically completes in under 500ms. File validators that call external tools (shellcheck, terraform) are the slowest and have configurable timeouts.

What's the difference between global and project config?

Global config ($XDG_CONFIG_HOME/klaudiush/config.toml, default ~/.config/klaudiush/config.toml) applies to all projects - use it for your personal preferences. Project config (.klaudiush/config.toml) applies to one repository and overrides global settings - use it for team standards.

Validators

How do I disable a validator?

Three ways, in order of precedence:

# CLI flag (highest precedence)
klaudiush --disable=commit,markdown --hook-type PreToolUse

# Environment variable
KLAUDIUSH_VALIDATORS_GIT_COMMIT_ENABLED=false

# Config file
# [validators.git.commit]
# enabled = false

Or in your config file:

[validators.git.commit]
enabled = false

What's the difference between "error" and "warning" severity?

Error severity blocks the operation - Claude Code sees a deny response and can't proceed. Warning severity logs the issue but allows the operation through. The default is error.

Why is my commit message rejected?

Common reasons: title exceeds 50 characters (configurable via title_max_length), missing scope when require_scope = true, invalid conventional commit type, or missing signoff flag (-s). Check the error code in the response for the specific issue.

Configuration

How do I validate my config file?

Run klaudiush debug config to see the loaded config and any parsing errors. The klaudiush doctor --category config command also checks config validity.

Can I use regex in patterns?

Yes. The rule engine auto-detects glob vs regex patterns. If the pattern contains anchors (^, $), character classes ([), or quantifiers (+, .*), it's treated as regex. Otherwise it's a glob.

How do I bypass a validation error?

Use the exception workflow with tokens in your command:

# Shell comment
git push origin main  # EXC:GIT019:Emergency+hotfix

# Environment variable
KLACK="EXC:SEC001:Test+fixture" git commit -sS -m "msg"

You need to configure an exception policy for the error code:

[exceptions]
enabled = true

[exceptions.policies.GIT019]
enabled = true
allow_exception = true
require_reason = true

Troubleshooting

How do I get shell completions?

klaudiush completion bash | sudo tee /usr/local/etc/bash_completion.d/klaudiush
klaudiush completion zsh | sudo tee /usr/local/share/zsh/site-functions/_klaudiush
klaudiush completion fish > ~/.config/fish/completions/klaudiush.fish

Where are logs and state files stored?

Logs go to $XDG_STATE_HOME/klaudiush/dispatcher.log (default ~/.local/state/klaudiush/dispatcher.log). Override with the KLAUDIUSH_LOG_FILE environment variable. Exception audit logs are at $XDG_STATE_HOME/klaudiush/exception_audit.jsonl. The old symlink at ~/.claude/hooks/dispatcher.log still works after migration.