jdx/hk

hk

Git hooks and project checks, in parallel.

hk runs linters and fixers in parallel. Read/write file locks keep them from colliding when steps touch the same files, so concurrency within a run doesn't cost you correctness. Steps configured with stomp skip the locks, and separate hk processes don't share them. Use the same steps in Git hooks, from your terminal, and in CI.

Get started · Documentation · Built-in linters · CLI reference

Quick start

Install with mise, then run these commands inside your repository:

mise use hk
hk init
hk install
hk check --all

hk init detects project tools and generates hk.pkl. Review the selected linters and make sure their executables are available on PATH; hk configures how to run them, but does not install them. Use hk init --interactive to choose tools yourself.

On Git 2.54+, you can run hk install --global once to enable hk across repositories. Installed hooks exit silently in projects without an hk configuration. See installation options for older Git versions and mise environments.

You can also install hk with brew install hk or cargo install hk --locked. The default Pkl evaluator is built into hk; a separate Pkl installation is optional.

A configuration you can share

This example uses hk’s built-in whitespace utilities, so it needs no additional linter:

amends "package://github.com/jdx/hk/releases/download/v2.11.1/[email protected]#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v2.11.1/[email protected]#/Builtins.pkl"

steps {
  ["trailing-whitespace"] = Builtins.trailing_whitespace
  ["newlines"] = Builtins.newlines
}

Top-level steps is the recommended starting point: hk supplies check, fix, and pre-commit hooks using these steps. It is optional; you can also define steps only inside explicit hooks. See hook defaults.

Add tools such as Builtins.oxfmt, Builtins.eslint, or Builtins.ruff, or define your own steps.

Everyday commands

By convention, checks do not modify files. hk fix leaves fixes unstaged unless you pass --stage. The default pre-commit hook stashes unstaged work, fixes and stages changes, then restores the unstaged work. Review git diff and git diff --cached. Learn about hooks and partial commits.

Why hk?

• Coordinate concurrent tools. File locks protect overlapping steps; diff and file-list checks reduce the work that needs exclusive access.
• Reuse linter configurations. Builtins describe file patterns, check commands, fixes, and tool-specific optimizations.
• Keep configuration maintainable. Pkl provides types, imports, and reusable objects for sharing steps across hooks and projects.
• Use your existing toolchain. Run commands from PATH, or use mise to manage tools and environments.

Read how hk works, browse project examples, or see the benchmark methodology and results.

Demo

Agent skills

hk includes two skills for coding agents:

• hk-configure: add linters and custom checks, preserve the project's Pkl schema version, and verify which files each step selects.
• hk-debug: diagnose hook failures, skipped steps, configuration overrides, and partially staged files.

Both skills ship in the skills/ directory of each release archive. hk's packslip manifest points to those directories, so compatible installers can use the bundled instructions without a separate repository download. Making them available to an agent is opt-in; see mise's skills documentation.

Contributing

See the contributing guide for development setup, tests, and review expectations. hk is released under the MIT license.

Sponsors

Sponsored by

   

View all sponsors

Thanks to Namespace for providing CI for hk.