Configuration

TOML schema and precedence rules

On this page

Overview
File locations
Precedence
Schema reference
JSON schema
Deep merge
Full example

Overview

klaudiush uses TOML configuration files. You can have a global config that applies to all projects and per-project configs that override specific settings. CLI flags and environment variables take precedence over config files. All validators have sensible defaults - a config file is optional.

File locations

Path	Description
`$XDG_CONFIG_HOME/klaudiush/config.toml`	Global config (default `~/.config/klaudiush/`)
`.klaudiush/config.toml`	Project config (this repo)
`klaudiush.toml`	Alternative project config location

The global config follows the XDG Base Directory specification. Project configs sit in the repo root (either in a .klaudiush/ directory or as a standalone file) and override global settings for that repo.

Automatic migration

If you're upgrading from a version that used ~/.klaudiush/config.toml, klaudiush migrates your files to XDG locations on first run. A symlink is left at the old path for backward compatibility. If the file exists at ~/.klaudiush/config.toml but not the XDG location, klaudiush still reads it as a fallback.

You can also point to custom config paths with CLI flags:

klaudiush --config=./my-config.toml --hook-type PreToolUse
klaudiush --disable=commit,markdown --hook-type PreToolUse
klaudiush --global-config=~/.config/klaudiush.toml --hook-type PreToolUse

Precedence

Configuration loads from multiple sources, highest precedence first:

CLI flags (--disable, --config)
Environment variables (KLAUDIUSH_*)
Project config (.klaudiush/config.toml)
Global config ($XDG_CONFIG_HOME/klaudiush/config.toml)
Built-in defaults

Environment variable overrides use the KLAUDIUSH_ prefix with hierarchical naming:

KLAUDIUSH_VALIDATORS_GIT_COMMIT_ENABLED=false
KLAUDIUSH_VALIDATORS_GIT_COMMIT_MESSAGE_TITLE_MAX_LENGTH=72
KLAUDIUSH_VALIDATORS_FILE_MARKDOWN_ENABLED=false
KLAUDIUSH_USE_SDK_GIT=false

Schema reference

A complete config file with all available options and their defaults. Every validator can be enabled/disabled individually with the enabled key.

[validators.git.commit]
enabled = true
required_flags = ["-s", "-S"]
check_staging_area = true
enable_message_validation = true

[validators.git.commit.message]
title_max_length = 50
body_max_line_length = 72
check_conventional_commits = true
valid_types = ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"]
require_scope = true

[validators.git.push]
enabled = true

[validators.git.pr]
enabled = true
title_max_length = 50

[validators.git.branch]
enabled = true
protected_branches = ["main", "master"]

[validators.file.markdown]
enabled = true
timeout = "10s"

[validators.file.shellscript]
enabled = true
timeout = "10s"

[validators.file.terraform]
enabled = true
check_format = true
use_tflint = true

[validators.file.workflow]
enabled = true
enforce_digest_pinning = true

[validators.shell.backtick]
enabled = true
check_all_commands = false

[validators.notification.bell]
enabled = true

Config loading time

Config loads from all sources in under 45 microseconds. There's no performance penalty for using multiple config files.

JSON schema

A machine-readable JSON Schema (draft 2020-12) is published for the configuration format. It defines every property, type constraint, enum value, and nested structure.

https://klaudiu.sh/schema/v1/config.json

The schema is generated from the Go config structs and stays in sync with each release. It covers all top-level sections (validators, rules, plugins, backup, exceptions, patterns, crash_dump, global) and their full type hierarchy.

Use cases

Validate config files programmatically before deployment
Generate config documentation or forms from the schema
Editor autocompletion in IDEs that support JSON Schema for TOML
CI checks that catch config typos before they hit production

Validating a config file

Convert your TOML config to JSON, then validate it against the schema with any JSON Schema validator. Example using yq and ajv:

# Convert TOML to JSON, then validate against the schema
yq -p toml -o json .klaudiush/config.toml | \
  ajv validate -s <(curl -s https://klaudiu.sh/schema/v1/config.json) -d -

Schema versioning

The schema URL includes the version (/v1/). If the config format changes in a backward-incompatible way, a new version will be published at /v2/ while the old one remains available.

Deep merge

When project and global configs both define the same section, values are deep-merged rather than replaced. Project values win on conflict, but unset project keys preserve the global value.

# Global: $XDG_CONFIG_HOME/klaudiush/config.toml
[validators.git.commit.message]
title_max_length = 50
require_scope = true

# Project: .klaudiush/config.toml
[validators.git.commit.message]
title_max_length = 72

# Result after merge:
# title_max_length = 72  (project wins)
# require_scope = true   (preserved from global)

Full example

Browse the general config examples for ready-to-use configs: minimal setup, full reference, project overrides, and language-specific configs (JavaScript, Rust).

To inspect your currently loaded config, run:

klaudiush --config=./my-config.toml --hook-type PreToolUse
klaudiush --disable=commit,markdown --hook-type PreToolUse
klaudiush --global-config=~/.config/klaudiush.toml --hook-type PreToolUse