hk

name	hk
description	Use when hk.pkl exists in project, hook output shows hk running, or working with git hooks in hk-managed projects. Also use when setting up, configuring, or troubleshooting hk git hooks.

hk - Git Hook Manager

Overview

hk is a fast git hook manager by jdx (author of mise). Uses pkl configuration language. Provides 90+ built-in linters.

Docs: https://hk.jdx.dev/ GitHub: https://github.com/jdx/hk

Detection

Identify which hook manager a project uses:

File	Hook Manager
hk.pkl	hk
lefthook.yml	lefthook
.husky/ directory	husky
.pre-commit-config.yaml	pre-commit (python)

Key Commands

hk init              # Create initial hk.pkl
hk install           # Set up git hooks
hk check             # Run checks manually (read-only)
hk fix               # Auto-fix issues
hk builtins          # List available builtins
hk validate          # Validate config
hk config dump       # Show effective configuration

Core Concepts

• Hooks: Git hook types (pre-commit, commit-msg, pre-push)
• Steps: Named units of work within hooks
• Builtins: Pre-configured linters (90+) via Builtins.pkl
• Profiles: Enable/disable groups of steps (--profile slow)

Configuration

When editing hk.pkl, read hk-pkl-reference.md in this skill directory for structure and examples.

Built-in Linters

When looking up builtins, read builtins-reference.md in this skill directory. Or run hk builtins for the live list.

Finding Help

Stable reference: Read the reference files in this skill directory when needed.

Latest docs:

npx @mdream/crawl https://hk.jdx.dev/ --output /tmp/hk-docs

GitHub issues:

gh issue list -R jdx/hk                    # List open issues
gh search issues --repo jdx/hk "error"     # Search issues
gh issue view 123 -R jdx/hk                # View specific issue

Troubleshooting

Hook not running:

hk install        # Reinstall hooks
cat .git/hooks/pre-commit  # Verify hook calls hk

Step skipped:

hk check -v       # Verbose output shows skip reasons
hk config dump    # Check effective configuration

Validate config:

hk validate       # Check hk.pkl syntax