hk

hk

Git hooks and project checks, in parallel.

hk runs linters and formatters with read/write file locks, so independent work runs concurrently and tools that modify the same files take turns. 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.

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

amends "package://github.com/jdx/hk/releases/download/v2.3.1/[email protected]#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v2.3.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.prettier, Builtins.eslint, or Builtins.ruff, or define your own steps.

Everyday commands

Command	Use it to
hk check	Check modified files
hk fix	Apply available fixes to modified files
hk check --all	Check the repository, including in CI
hk check --plan	Preview selected files and steps without running them
hk check --why prettier	Explain why a step will run or be skipped

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
[

](https://omarchy.org/patrons/)

View all sponsors

Thanks to Namespace for providing CI for hk.

---

Summary

Git hooks and project checks, in parallel (1.2k stars, MIT, Rust; by jdx of mise): linters/formatters run concurrently under read/write file locks — independent tools in parallel, same-file tools serialized; the SAME steps run in git hooks, terminal, and CI. mise-installable, built-in linters.

Learnings

• The unifier the Golden repo hook section wanted: one config, three contexts (hook/CLI/CI) — kills the ‘hooks pass locally, CI differs’ drift. Same author as mise; install path mise use hk. Sits beside prek (pre-commit-compatible) as the Rust-performance school with a different bet: locks-based parallelism vs prek’s pre-commit ecosystem reuse.

Gotchas

• (none yet)

Hands-on

(todo: try on a small repo vs prek)