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

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/v1.58.1/hk@1.58.1#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.58.1/hk@1.58.1#/Builtins.pkl"

local linters = new Mapping<String, Step> {
  ["trailing-whitespace"] = Builtins.trailing_whitespace
  ["newlines"] = Builtins.newlines
}

hooks {
  ["pre-commit"] {
    fix = true
    stash = "git"
    steps = linters
  }
  ["check"] { steps = linters }
  ["fix"] {
    fix = true
    steps = linters
  }
}

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

By convention, checks do not modify files. Fixes may modify and stage files; review git diff and git diff --cached. Use hk fix --no-stage to leave fixes unstaged. The generated pre-commit hook stashes unstaged work before fixing staged files, then restores it afterward. Learn about hooks and partial commits.

• 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.

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.

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

Sponsored by

   

View all sponsors

Thanks to Namespace for providing CI for hk.