Klaudiush

A validation dispatcher for AI coding-agent hooks. Klaudiush supports Claude Code hooks today and experimental Codex command hooks, enforcing git workflow standards, commit conventions, and code quality rules.

For Claude, klaudiush runs in blocking before_tool flows (PreToolUse). For Codex, it can also participate in experimental session_start, after_tool, and turn_stop command hooks. It parses Bash commands via mvdan.cc/sh, detects file operations, and validates them against project-specific rules.

Git workflow validation (commits, pushes, branches, PRs)
Code quality checks (shellcheck, terraform fmt, actionlint, gofumpt, ruff, oxlint, rustfmt)
Bash AST parsing for command chains, pipes, subshells, redirections
File write detection and path protection
Secret detection (25+ patterns, optional gitleaks integration)
Dynamic validation rules via TOML

Installation

Homebrew

brew install smykla-skalski/tap/klaudiush

Install script

curl -sSfL https://klaudiu.sh/install.sh | sh

# Specific version or custom directory
curl -sSfL https://klaudiu.sh/install.sh | sh -s -- -v v1.0.0
curl -sSfL https://klaudiu.sh/install.sh | sh -s -- -b /usr/local/bin

Nix

nix run github:smykla-skalski/klaudiush?dir=nix
nix profile install github:smykla-skalski/klaudiush?dir=nix

Home Manager module:

{
  inputs.klaudiush.url = "github:smykla-skalski/klaudiush?dir=nix";
}

{
  imports = [ inputs.klaudiush.homeManagerModules.default ];
  programs.klaudiush.enable = true;
}

Build from source

mise run build && mise run install

Setup

After installing, register the hooks and verify:

klaudiush init --global
klaudiush doctor

The binary installs to ~/.local/bin or ~/bin. Make sure the install directory is in your $PATH.

Shell completions are available for bash, zsh, fish, and PowerShell via klaudiush completion <shell>.

How it works

Provider Hook JSON -> CLI -> JSON Parser -> Dispatcher -> Registry -> Validators -> Result

Claude Code and Codex send hook payloads as JSON on stdin. Klaudiush normalizes the provider payload, matches it against registered validators using a predicate system, and returns a result: pass (no output), deny/block (JSON on stdout), or warn/advisory context. Exit code is always 0. On crash, exit code 3 with panic info on stderr.

Validators register with predicates that control when they fire:

registry.Register(validator, validator.And(
    validator.EventIs(hook.CanonicalEventBeforeTool),
    validator.ToolTypeIs(hook.Bash),
    validator.CommandContains("git commit"),
))

Available predicates: EventIs, EventTypeIs, ProviderIs, ToolTypeIs, CommandContains, FileExtensionIs, FilePathMatches, And, Or, Not.

Validators

Git validators handle commit message format (conventional commits, <=50 char title, <=72 char body), required flags (-sS), branch naming (type/description), push policies, PR validation (title, body, changelog), and staging rules.

File validators run shellcheck, terraform/tofu fmt + tflint, GitHub Actions digest pinning + actionlint, gofumpt, ruff, oxlint, and rustfmt. Markdown formatting is checked too.

Secrets detection covers 25+ regex patterns for AWS keys, GitHub tokens, private keys, and connection strings. Optional gitleaks integration with configurable allow lists.

Shell validators detect backticks in commit/PR commands, with an optional comprehensive mode for all Bash commands.

A notification validator rings the terminal bell on permission prompts (dock bounce on macOS).

Configuration

No configuration is required. All validators have working defaults.

Klaudiush uses TOML configuration with this precedence (highest first):

CLI flags (--disable=commit,markdown)
Environment variables (KLAUDIUSH_VALIDATORS_GIT_COMMIT_ENABLED=false)
Project config (.klaudiush/config.toml)
Global config ($XDG_CONFIG_HOME/klaudiush/config.toml)
Built-in defaults

Sources are deep-merged - nested values merge rather than replace.

# Disable commit validation
[validators.git.commit]
enabled = false

# Allow longer titles
[validators.git.commit.message]
title_max_length = 72

# Downgrade shellscript to warning
[validators.file.shellscript]
severity = "warning"

All validators support enabled (on/off) and severity ("error" to block, "warning" to log only). Git validators add options for message format, required flags, branch naming, and push policies. File validators add timeouts and per-linter configuration.

See examples/config/ for complete examples with all options.

Dynamic rules

The rule engine lets you block, warn, or allow operations based on patterns without code changes:

[rules]
enabled = true

[[rules.rules]]
name = "block-main-push"
priority = 100

[rules.rules.match]
validator_type = "git.push"
branch_pattern = "main"

[rules.rules.action]
type = "block"
message = "Direct push to main is not allowed. Use a pull request."

Rules support glob and regex patterns (auto-detected), priority ordering, validator scoping (git.push or git.*), and negation. See the rules guide and examples/rules/.

Exception workflow

Bypass a validation block by adding an exception token to the command:

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

Exceptions require explicit policy configuration per error code, enforce rate limits, and log to an audit trail. See the exceptions guide.

Exceptions only apply to blocking before_tool command flows. They are not used for Codex lifecycle hooks.

Performance

End-to-end binary execution on Apple M3 Max (hyperfine, 30 runs, CLI git backend):

Payload	Time
Baseline (empty stdin)	59ms +/- 7ms
Non-git bash	68ms +/- 6ms
Git commit (full validation)	112ms +/- 6ms
Git push	87ms +/- 4ms

Internal micro-benchmarks: JSON parse 0.5-3.6us, Bash AST parse 1.4-23us, dispatcher overhead 1.2-1.8us per dispatch.

The default git SDK backend (go-git/v6) is 2-5.9M times faster than CLI for cached operations. Set KLAUDIUSH_USE_SDK_GIT=false to use the CLI fallback.

mise run bench             # in-process micro-benchmarks
mise run bench:hyperfine   # end-to-end comparison

Development

mise run test       # all tests
mise run verify     # fmt + lint + test
mise run check      # lint + auto-fix

Add validators in internal/validators/{category}/, implement Validate(), register in cmd/klaudiush/main.go with predicates. Logs go to $XDG_STATE_HOME/klaudiush/dispatcher.log.

The project uses Lefthook for git hooks. Run mise run install:hooks to set up pre-commit (staged files only) and pre-push (full suite) hooks.

Contributing

Create a feature branch (feat/my-feature)
Write tests first
Run mise run verify
Open a PR with a semantic title

klaudiush